pw_sync: Clarify PW_LOCKS_EXCLUDED documentation

The documentation of PW_LOCKS_EXCLUDED previously stated that the
annotated function acquired the lock in question. However, this is only
one possible use of the annotation. The annotated function may wish to
guarantee that a lock is not held for other purposes, such as ensuring
that the code in question is not run as part of a critical section.

Change-Id: If209df1c38f097a51f93f40ff2b5c9168b9993e8
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/103421
Commit-Queue: Taylor Cramer <cramertj@google.com>
Reviewed-by: Wyatt Hepler <hepler@google.com>

pw_sync/docs.rst

@@ -755,9 +755,10 @@ Annotating Lock Usage
 
 .. cpp:function:: PW_LOCKS_EXCLUDED(...)
 
-  Documents the locks acquired in the body of the function. These locks
-  cannot be held when calling this function (as Pigweed's default locks are
-  non-reentrant).
+  Documents that the caller must not hold the given lock. This annotation is
+  often used to prevent deadlocks. Pigweed's mutex implementation is not
+  re-entrant, so a deadlock will occur if the function acquires the mutex a
+  second time.
 
   Example:
 

pw_sync/public/pw_sync/lock_annotations.h

@@ -149,9 +149,10 @@
 
 // PW_LOCKS_EXCLUDED()
 //
-// Documents the locks acquired in the body of the function. These locks
-// cannot be held when calling this function (as Pigweed's default locks are
-// non-reentrant).
+// Documents that the caller must not hold the given lock. This annotation is
+// often used to prevent deadlocks. Pigweed's mutex implementation is not
+// re-entrant, so a deadlock will occur if the function acquires the mutex a
+// second time.
 #if PW_HAVE_ATTRIBUTE(locks_excluded)
 #define PW_LOCKS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__)))
 #else