--- 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
 !