Re: Code snippets in documentation

Welp, the "snippets.patch" file was scrubbed by the mailing list.
Although it is available via the web interface (
http://cs.oswego.edu/pipermail/concurrency-interest/2020-November/017264.html
), let me also include it inline for the reader's convenience.

---

Index: src/main/java/util/concurrent/AbstractExecutorService.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/AbstractExecutorService.java,v
retrieving revision 1.53
diff -U 2 -d -r1.53 AbstractExecutorService.java
--- src/main/java/util/concurrent/AbstractExecutorService.java 24 Jul
2020 20:54:37 -0000 1.53
+++ src/main/java/util/concurrent/AbstractExecutorService.java 25 Nov
2020 15:45:53 -0000
@@ -26,5 +26,5 @@
  * {@code FutureTask}.
  *
- * <p><b>Extension example</b>. Here is a sketch of a class
+ * <p><b>Extension example.</b> Here is a sketch of a class
  * that customizes {@link ThreadPoolExecutor} to use
  * a {@code CustomTask} class instead of the default {@code FutureTask}:
@@ -32,5 +32,5 @@
  * public class CustomThreadPoolExecutor extends ThreadPoolExecutor {
  *
- *   static class CustomTask<V> implements RunnableFuture<V> {...}
+ *   static class CustomTask<V> implements RunnableFuture<V> { ... }
  *
  *   protected <V> RunnableFuture<V> newTaskFor(Callable<V> c) {
Index: src/main/java/util/concurrent/CopyOnWriteArraySet.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/CopyOnWriteArraySet.java,v
retrieving revision 1.74
diff -U 2 -d -r1.74 CopyOnWriteArraySet.java
--- src/main/java/util/concurrent/CopyOnWriteArraySet.java 1 Oct 2018
00:10:53 -0000 1.74
+++ src/main/java/util/concurrent/CopyOnWriteArraySet.java 25 Nov 2020
15:45:53 -0000
@@ -41,5 +41,5 @@
  *
  * <pre> {@code
- * class Handler { void handle(); ... }
+ * class Handler { void handle() { ... } }
  *
  * class X {
Index: src/main/java/util/concurrent/CountDownLatch.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/CountDownLatch.java,v
retrieving revision 1.44
diff -U 2 -d -r1.44 CountDownLatch.java
--- src/main/java/util/concurrent/CountDownLatch.java 17 Feb 2015
18:55:39 -0000 1.44
+++ src/main/java/util/concurrent/CountDownLatch.java 25 Nov 2020 15:45:53 -0000
@@ -90,5 +90,5 @@
  *   void main() throws InterruptedException {
  *     CountDownLatch doneSignal = new CountDownLatch(N);
- *     Executor e = ...
+ *     Executor e = ...;
  *
  *     for (int i = 0; i < N; ++i) // create and start threads
@@ -107,8 +107,6 @@
  *   }
  *   public void run() {
- *     try {
- *       doWork(i);
- *       doneSignal.countDown();
- *     } catch (InterruptedException ex) {} // return;
+ *     doWork();
+ *     doneSignal.countDown();
  *   }
  *
Index: src/main/java/util/concurrent/CountedCompleter.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/CountedCompleter.java,v
retrieving revision 1.68
diff -U 2 -d -r1.68 CountedCompleter.java
--- src/main/java/util/concurrent/CountedCompleter.java 20 Jan 2020
15:51:54 -0000 1.68
+++ src/main/java/util/concurrent/CountedCompleter.java 25 Nov 2020
15:45:53 -0000
@@ -329,5 +329,5 @@
  * this task or other completed tasks.
  *
- * <p><b>Completion Traversals</b>. If using {@code onCompletion} to
+ * <p><b>Completion Traversals.</b> If using {@code onCompletion} to
  * process completions is inapplicable or inconvenient, you can use
  * methods {@link #firstComplete} and {@link #nextComplete} to create
Index: src/main/java/util/concurrent/CyclicBarrier.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/CyclicBarrier.java,v
retrieving revision 1.61
diff -U 2 -d -r1.61 CyclicBarrier.java
--- src/main/java/util/concurrent/CyclicBarrier.java 2 Feb 2019
04:09:54 -0000 1.61
+++ src/main/java/util/concurrent/CyclicBarrier.java 25 Nov 2020 15:45:53 -0000
@@ -66,5 +66,7 @@
  *     // wait until done
  *     for (Thread thread : threads)
- *       thread.join();
+ *       try {
+ *         thread.join();
+ *       } catch (InterruptedException ex) { }
  *   }
  * }}</pre>
Index: src/main/java/util/concurrent/Exchanger.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/Exchanger.java,v
retrieving revision 1.84
diff -U 2 -d -r1.84 Exchanger.java
--- src/main/java/util/concurrent/Exchanger.java 22 Nov 2018 00:47:00 -0000 1.84
+++ src/main/java/util/concurrent/Exchanger.java 25 Nov 2020 15:45:53 -0000
@@ -29,6 +29,6 @@
  * class FillAndEmpty {
  *   Exchanger<DataBuffer> exchanger = new Exchanger<>();
- *   DataBuffer initialEmptyBuffer = ... a made-up type
- *   DataBuffer initialFullBuffer = ...
+ *   DataBuffer initialEmptyBuffer = ...; // a made-up type
+ *   DataBuffer initialFullBuffer = ...;
  *
  *   class FillingLoop implements Runnable {
@@ -41,5 +41,5 @@
  *             currentBuffer = exchanger.exchange(currentBuffer);
  *         }
- *       } catch (InterruptedException ex) { ... handle ... }
+ *       } catch (InterruptedException ex) { ... handle ...}
  *     }
  *   }
Index: src/main/java/util/concurrent/ExecutorService.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/ExecutorService.java,v
retrieving revision 1.64
diff -U 2 -d -r1.64 ExecutorService.java
--- src/main/java/util/concurrent/ExecutorService.java 7 Mar 2019
00:50:36 -0000 1.64
+++ src/main/java/util/concurrent/ExecutorService.java 25 Nov 2020
15:45:53 -0000
@@ -89,5 +89,5 @@
  *           System.err.println("Pool did not terminate");
  *     }
- *   } catch (InterruptedException ie) {
+ *   } catch (InterruptedException ex) {
  *     // (Re-)Cancel if current thread also interrupted
  *     pool.shutdownNow();
Index: src/main/java/util/concurrent/ForkJoinPool.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/ForkJoinPool.java,v
retrieving revision 1.385
diff -U 2 -d -r1.385 ForkJoinPool.java
--- src/main/java/util/concurrent/ForkJoinPool.java 13 Nov 2020
15:24:36 -0000 1.385
+++ src/main/java/util/concurrent/ForkJoinPool.java 25 Nov 2020 15:45:54 -0000
@@ -138,5 +138,5 @@
  * cause unjoined tasks to never be executed.
  *
- * <p><b>Implementation notes</b>: This implementation restricts the
+ * <p><b>Implementation notes:</b> This implementation restricts the
  * maximum number of running threads to 32767. Attempts to create
  * pools with greater than the maximum number result in
Index: src/main/java/util/concurrent/Future.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/Future.java,v
retrieving revision 1.42
diff -U 2 -d -r1.42 Future.java
--- src/main/java/util/concurrent/Future.java 18 Sep 2020 14:33:57 -0000 1.42
+++ src/main/java/util/concurrent/Future.java 25 Nov 2020 15:45:54 -0000
@@ -28,6 +28,6 @@
  * interface ArchiveSearcher { String search(String target); }
  * class App {
- *   ExecutorService executor = ...
- *   ArchiveSearcher searcher = ...
+ *   ExecutorService executor = ...;
+ *   ArchiveSearcher searcher = ...;
  *   void showSearch(String target) throws InterruptedException {
  *     Callable<String> task = () -> searcher.search(target);
Index: src/main/java/util/concurrent/Phaser.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/Phaser.java,v
retrieving revision 1.95
diff -U 2 -d -r1.95 Phaser.java
--- src/main/java/util/concurrent/Phaser.java 12 Aug 2019 22:05:32 -0000 1.95
+++ src/main/java/util/concurrent/Phaser.java 25 Nov 2020 15:45:54 -0000
@@ -217,5 +217,5 @@
  * high rates), or up to hundreds for extremely large ones.
  *
- * <p><b>Implementation notes</b>: This implementation restricts the
+ * <p><b>Implementation notes:</b> This implementation restricts the
  * maximum number of parties to 65535. Attempts to register additional
  * parties result in {@code IllegalStateException}. However, you can and
@@ -891,5 +891,5 @@
      * Phaser phaser = new Phaser() {
      *   protected boolean onAdvance(int phase, int parties) { return false; }
-     * }}</pre>
+     * };}</pre>
      *
      * @param phase the current phase number on entry to this method,
Index: src/main/java/util/concurrent/PriorityBlockingQueue.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/PriorityBlockingQueue.java,v
retrieving revision 1.145
diff -U 2 -d -r1.145 PriorityBlockingQueue.java
--- src/main/java/util/concurrent/PriorityBlockingQueue.java 24 Jul
2020 20:57:26 -0000 1.145
+++ src/main/java/util/concurrent/PriorityBlockingQueue.java 25 Nov
2020 15:45:54 -0000
@@ -59,5 +59,5 @@
  * class FIFOEntry<E extends Comparable<? super E>>
  *     implements Comparable<FIFOEntry<E>> {
- *   static final AtomicLong seq = new AtomicLong(0);
+ *   static final AtomicLong seq = new AtomicLong();
  *   final long seqNum;
  *   final E entry;
Index: src/main/java/util/concurrent/Semaphore.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/Semaphore.java,v
retrieving revision 1.77
diff -U 2 -d -r1.77 Semaphore.java
--- src/main/java/util/concurrent/Semaphore.java 19 Apr 2017 23:45:51 -0000 1.77
+++ src/main/java/util/concurrent/Semaphore.java 25 Nov 2020 15:45:54 -0000
@@ -38,5 +38,5 @@
  *   // Not a particularly efficient data structure; just for demo
  *
- *   protected Object[] items = ... whatever kinds of items being managed
+ *   protected Object[] items = ...; // whatever kinds of items being managed
  *   protected boolean[] used = new boolean[MAX_AVAILABLE];
  *
Index: src/main/java/util/concurrent/ThreadPoolExecutor.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/ThreadPoolExecutor.java,v
retrieving revision 1.193
diff -U 2 -d -r1.193 ThreadPoolExecutor.java
--- src/main/java/util/concurrent/ThreadPoolExecutor.java 31 Jul 2020
17:18:14 -0000 1.193
+++ src/main/java/util/concurrent/ThreadPoolExecutor.java 25 Nov 2020
15:45:54 -0000
@@ -249,5 +249,5 @@
  * </dl>
  *
- * <p><b>Extension example</b>. Most extensions of this class
+ * <p><b>Extension example.</b> Most extensions of this class
  * override one or more of the protected hook methods. For example,
  * here is a subclass that adds a simple pause/resume feature:
Index: src/main/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java,v
retrieving revision 1.86
diff -U 2 -d -r1.86 AtomicReferenceFieldUpdater.java
--- src/main/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
14 Oct 2018 10:37:12 -0000 1.86
+++ src/main/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
25 Nov 2020 15:45:55 -0000
@@ -34,5 +34,5 @@
  *   private static final AtomicReferenceFieldUpdater<Node, Node> leftUpdater =
  *     AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "left");
- *   private static AtomicReferenceFieldUpdater<Node, Node> rightUpdater =
+ *   private static final AtomicReferenceFieldUpdater<Node, Node>
rightUpdater =
  *     AtomicReferenceFieldUpdater.newUpdater(Node.class, Node.class, "right");
  *
Index: src/main/java/util/concurrent/atomic/package-info.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/atomic/package-info.java,v
retrieving revision 1.20
diff -U 2 -d -r1.20 package-info.java
--- src/main/java/util/concurrent/atomic/package-info.java 24 Sep 2016
15:21:54 -0000 1.20
+++ src/main/java/util/concurrent/atomic/package-info.java 25 Nov 2020
15:45:55 -0000
@@ -26,5 +26,5 @@
  * class Sequencer {
  *   private final AtomicLong sequenceNumber
- *     = new AtomicLong(0);
+ *     = new AtomicLong(17);
  *   public long next() {
  *     return sequenceNumber.getAndIncrement();
Index: src/main/java/util/concurrent/locks/AbstractQueuedSynchronizer.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/locks/AbstractQueuedSynchronizer.java,v
retrieving revision 1.183
diff -U 2 -d -r1.183 AbstractQueuedSynchronizer.java
--- src/main/java/util/concurrent/locks/AbstractQueuedSynchronizer.java
21 Sep 2019 18:00:23 -0000 1.183
+++ src/main/java/util/concurrent/locks/AbstractQueuedSynchronizer.java
25 Nov 2020 15:45:55 -0000
@@ -109,5 +109,5 @@
  *
  * <pre>
- * Acquire:
+ * <em>Acquire:</em>
  *     while (!tryAcquire(arg)) {
  *        <em>enqueue thread if it is not already queued</em>;
@@ -115,5 +115,5 @@
  *     }
  *
- * Release:
+ * <em>Release:</em>
  *     if (tryRelease(arg))
  *        <em>unblock the first queued thread</em>;
Index: src/main/java/util/concurrent/locks/ReentrantLock.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/locks/ReentrantLock.java,v
retrieving revision 1.121
diff -U 2 -d -r1.121 ReentrantLock.java
--- src/main/java/util/concurrent/locks/ReentrantLock.java 26 Apr 2020
16:43:22 -0000 1.121
+++ src/main/java/util/concurrent/locks/ReentrantLock.java 25 Nov 2020
15:45:55 -0000
@@ -522,5 +522,5 @@
      * <pre> {@code
      * class X {
-     *   ReentrantLock lock = new ReentrantLock();
+     *   final ReentrantLock lock = new ReentrantLock();
      *   // ...
      *   public void m() {
@@ -552,5 +552,5 @@
      * <pre> {@code
      * class X {
-     *   ReentrantLock lock = new ReentrantLock();
+     *   final ReentrantLock lock = new ReentrantLock();
      *   // ...
      *
@@ -566,5 +566,5 @@
      * <pre> {@code
      * class X {
-     *   ReentrantLock lock = new ReentrantLock();
+     *   final ReentrantLock lock = new ReentrantLock();
      *   // ...
      *
Index: src/main/java/util/concurrent/locks/ReentrantReadWriteLock.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/locks/ReentrantReadWriteLock.java,v
retrieving revision 1.137
diff -U 2 -d -r1.137 ReentrantReadWriteLock.java
--- src/main/java/util/concurrent/locks/ReentrantReadWriteLock.java 7
Mar 2019 00:50:36 -0000 1.137
+++ src/main/java/util/concurrent/locks/ReentrantReadWriteLock.java 25
Nov 2020 15:45:56 -0000
@@ -100,5 +100,5 @@
  * its state when serialized.
  *
- * <p><b>Sample usages</b>. Here is a code sketch showing how to perform
+ * <p><b>Sample usages.</b> Here is a code sketch showing how to perform
  * lock downgrading after updating a cache (exception handling is
  * particularly tricky when handling multiple locks in a non-nested
@@ -121,5 +121,5 @@
  *         // acquired write lock and changed state before we did.
  *         if (!cacheValid) {
- *           data = ...
+ *           data = ...;
  *           cacheValid = true;
  *         }
Index: src/main/java/util/concurrent/locks/StampedLock.java
===================================================================
RCS file: /home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/locks/StampedLock.java,v
retrieving revision 1.116
diff -U 2 -d -r1.116 StampedLock.java
--- src/main/java/util/concurrent/locks/StampedLock.java 16 Jul 2020
22:58:59 -0000 1.116
+++ src/main/java/util/concurrent/locks/StampedLock.java 25 Nov 2020
15:45:56 -0000
@@ -184,6 +184,6 @@
  *   }
  *
- *   // Upgrade read lock to write lock
- *   void moveIfAtOrigin(double newX, double newY) {
+ *   // upgrade read lock to write lock
+ *   void moveIfAtOrigin2(double newX, double newY) {
  *     long stamp = sl.readLock();
  *     try {

On Wed, Nov 25, 2020 at 3:48 PM Pavel Rappo <[email protected]> wrote:
>
> Hello,
>
> I'm currently looking into use of code snippets in doc comments in
> various codebases, one of which is `java.util.concurrent.**`. While
> looking at snippets there I found a few places that could be improved;
> I created a patch with these improvements.
>
> This patch is merely a collection of suggestions that can be applied
> selectively. I can provide the rationale for every change in that
> patch, but for now, I'd just say that those changes improve uniformity
> and correctness (where sensible).
>
> I used `cvs -q diff -U 2 --minimal > snippets.patch` to produce this
> patch. If you prefer some other form, I can produce it too.
>
> Thanks,
> -Pavel
_______________________________________________
Concurrency-interest mailing list
[email protected]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest