pw_thread: Improve docs for thread backends
Improves the verbiage in the documentation for thread backends
and that they may use native detached threads if and only if
PW_THREAD_JOINING_ENABLED is set to false.
Change-Id: I0d08c8a630ed64b81c585fe701510beaf3f5bcbc
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/110457
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Pigweed-Auto-Submit: Ewout van Bekkum <ewout@google.com>
Reviewed-by: Leonard Zgrablic <lzgrablic@google.com>
Reviewed-by: Wyatt Hepler <hepler@google.com>
diff --git a/pw_thread/docs.rst b/pw_thread/docs.rst
index 7581bbc..d9c17fe 100644
--- a/pw_thread/docs.rst
+++ b/pw_thread/docs.rst
@@ -228,8 +228,14 @@
core/processor affinity, and/or an optional reference to a pre-allocated
Context (the collection of memory allocations needed for a thread to run).
-Options shall NOT permit starting as detached, this must be done explicitly
-through the Thread API.
+Options shall NOT have an attribute to start threads as detached vs joinable.
+All ``pw::thread::Thread`` instances must be explicitly ``join()``'d or
+``detach()``'d through the run-time Thread API.
+
+Note that if backends set ``PW_THREAD_JOINING_ENABLED`` to false, backends
+may use native OS specific APIs to create native detached threads because the
+``join()`` API would be compiled out. However, users must still explicitly
+invoke ``detach()``.
Options must not contain any memory needed for a thread to run (TCB,
stack, etc.). The Options may be deleted or re-used immediately after
