8278255: Add more warning text in ReentrantLock and ReentrantReadWriteLock

Reviewed-by: prappo, alanb

Author: Viktor Klang

src/java.base/share/classes/java/util/concurrent/locks/Lock.java

@@ -80,11 +80,11 @@
  *
  * <pre> {@code
  * Lock l = ...;
- * l.lock();
+ * l.lock(); // lock() as the last statement before the try block
  * try {
  *   // access the resource protected by this lock
  * } finally {
- *   l.unlock();
+ *   l.unlock(); // unlock() as the first statement in the finally block
  * }}</pre>
  *
  * When locking and unlocking occur in different scopes, care must be

src/java.base/share/classes/java/util/concurrent/locks/ReentrantLock.java

@@ -71,20 +71,21 @@
  * is available even if other threads are waiting.
  *
  * <p>It is recommended practice to <em>always</em> immediately
- * follow a call to {@code lock} with a {@code try} block, most
- * typically in a before/after construction such as:
+ * follow a call to {@code lock} with a {@code try} block, and
+ * to <em>always</em> immediately call {@code unlock} as the
+ * first statement in the finally block, as follows:
  *
  * <pre> {@code
  * class X {
  *   private final ReentrantLock lock = new ReentrantLock();
  *   // ...
  *
  *   public void m() {
- *     lock.lock();  // block until condition holds
+ *     lock.lock();  // lock() as the last statement before the try block
  *     try {
  *       // ... method body
  *     } finally {
- *       lock.unlock();
+ *       lock.unlock(); // unlock() as the first statement in the finally block
  *     }
  *   }
  * }}</pre>

src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java

@@ -141,6 +141,7 @@
  *
  *   void processCachedData() {
  *     rwl.readLock().lock();
+ *     // Code between the lock() above, and the unlock() below must not throw
  *     if (!cacheValid) {
  *       // Must release read lock before acquiring write lock
  *       rwl.readLock().unlock();
@@ -158,7 +159,7 @@
  *         rwl.writeLock().unlock(); // Unlock write, still hold read
  *       }
  *     }
- *
+ *     // Make sure that code that could throw is executed inside the try block
  *     try {
  *       use(data);
  *     } finally {