pw_result: update docs
- Updates the pw::Result description.
- Adds a warning to not use larger types by value in Result.
Change-Id: I590892517251431bc11b8c0ed5718a152f294084
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/14643
Commit-Queue: Ewout van Bekkum <ewout@google.com>
Reviewed-by: Keir Mierle <keir@google.com>
diff --git a/pw_result/docs.rst b/pw_result/docs.rst
index db9ba14..5671d8a 100644
--- a/pw_result/docs.rst
+++ b/pw_result/docs.rst
@@ -7,10 +7,20 @@
---------
pw_result
---------
-``pw::Result`` is an experimental class that combines a status with a value to
-simplify writing and using APIs.
+``pw::Result`` is a convenient wrapper around returning a Status along side some
+data when the status is OK. This is meant for returning lightweight result
+types or references to larger results.
+
+.. warning::
+
+ Be careful not to use larger types by value as this can quickly consume
+ unnecessary stack.
.. warning::
This module is experimental. Its impact on code size and stack usage has not
yet been profiled. Use at your own risk.
+
+Compatibility
+=============
+Works with C++11, but some features require C++17.