--- a/AbstractLock.st	Thu Aug 31 10:17:00 2017 +0100
+++ b/AbstractLock.st	Fri Sep 01 05:10:15 2017 +0100
@@ -248,7 +248,10 @@
 
 critical:aBlock
     "Evaluate aBlock as a critical region. Same process may
-     enter critical region again, i.e., nesting allowed."
+     enter critical region again, i.e., nesting allowed.
+
+     Returns the (return) value of `aBlock`
+    "
     ^self critical: aBlock timeoutMs: nil ifBlocking: nil
 
     "Modified (comment): / 25-08-2017 / 09:47:36 / Jan Vrany <jan.vrany@fit.cvut.cz>"

--- a/RecursionLock.st	Thu Aug 31 10:17:00 2017 +0100
+++ b/RecursionLock.st	Fri Sep 01 05:10:15 2017 +0100
@@ -52,23 +52,47 @@
 
 documentation
 "
-    like a Semaphore for mutual exclusion, but avoids the deadlock
+    Like a Semaphore for mutual exclusion, but avoids the deadlock
     if a critical region is reentered by the same process again.
     I.e. allows reentering the critical region IFF the current process
     is the one which did the original locking.
 
+    NOTE:
+    The recursion lock is not only reentrant (same process may enter the
+    critical section multiple times) but also much faster than using
+    semaphore (`lock := Semaphore forMutualExclusion. lock critical:[...]`)
+
+    Therefore you're encouraged to use `RecursonLock` rather than
+    `Semaphore forMutualExclusion` whenever possible.
+
     WARNING:
-	for now, recursionLocks are not unlocked when an image is
+	For now, recursionLocks are not unlocked when an image is
 	restarted. You may have to recreate them to avoid a deadLock.
 	(this may change in the future, but recreating a recursionLock in
 	 the #earlyRestart handling does not hurt)
 
+    Thinlocks
+
+    RecursionLocks uses `thinlocks`[1] to optimize locking in the common
+    case - this makes it much faster.
+    The `lockword` is stored in `process` instvar - when a `process` instvar
+    contains a small integer, recursion lock is `thin`, value of `count` instvas
+    is invalid (out of sync).
+
+    [1]: David F. Bacon, Ravi Konuru, Chet Murthy, Mauricio Serrano:
+        Thin locks: featherweight synchronization for Java, ACM SIGPLAN 1998
+
+
+
     [author:]
-	Claus Gittinger
+	   Claus Gittinger
+        Jan Vrany (thinlock suppot)
 
     [see also:]
-	Semaphore
-	Process ProcessorScheduler
+	   Semaphore
+	   Process ProcessorScheduler
+        AbstractLock
+        thinlocks.h
 "
 !
 
@@ -331,7 +355,10 @@
 
 critical:aBlock
     "Evaluate aBlock as a critical region. Same process may
-     enter critical region again, i.e., nesting allowed."
+     enter critical region again, i.e., nesting allowed.
+
+     Returns the (return) value of `aBlock`
+    "
 
     <exception: #unwind>
 

--- a/Semaphore.st	Thu Aug 31 10:17:00 2017 +0100
+++ b/Semaphore.st	Fri Sep 01 05:10:15 2017 +0100
@@ -75,6 +75,10 @@
 	to a deadlock.
 	Use a RecursionLock instead, to avoid this.
 
+    NOTE:
+    You're encouraged to use `RecursionLock` for guarding a critical section.
+    `RecursionLock` is not only reentrant but also much faster.
+
     Hint:
 	now (Jul2002), Semaphores now allow for a negative count; this allows for
 	a sync-point to be implemented easily (i.e. to wait for multiple other processes
@@ -355,7 +359,7 @@
     "an optional reference to someone who owns this semaphore,
      typically a shared queue or a windowgroup or similar.
      This has no semantic meaning and is only used to support debugging"
-     
+
     ^ owner
 !