docs: add OS abstraction layers doc
Adds a new top level doc on Pigweed's OS abstraction layers.
While doing so, also adds some minor updates to the relevant modules.
Change-Id: Ie5c324088d06a1b4c6c11ff5abbbea03f4e9c61d
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/44920
Commit-Queue: Ewout van Bekkum <ewout@google.com>
Reviewed-by: Keir Mierle <keir@google.com>
diff --git a/pw_thread/docs.rst b/pw_thread/docs.rst
index c2b5ef3..99003cd 100644
--- a/pw_thread/docs.rst
+++ b/pw_thread/docs.rst
@@ -27,6 +27,13 @@
``pw::thread::ThreadCore`` objects and functions which match the
``pw::thread::Thread::ThreadRoutine`` signature.
+We recognize that the C++11's STL ``std::thread``` API has some drawbacks where
+it is easy to forget to join or detach the thread handle. Because of this, we
+offer helper wrappers like the ``pw::thread::DetachedThread``. Soon we will
+extend this by also adding a ``pw::thread::JoiningThread`` helper wrapper which
+will also have a lighter weight C++20 ``std::jthread`` like cooperative
+cancellation contract to make joining safer and easier.
+
Threads may begin execution immediately upon construction of the associated
thread object (pending any OS scheduling delays), starting at the top-level
function provided as a constructor argument. The return value of the