[concurrency-interest] Please clarify Javadoc of CompletableFuture.thenCompose()

Martin Buchholz martinrb at google.com
Mon Dec 1 13:24:12 EST 2014


On Sun, Nov 30, 2014 at 8:59 AM, Tim Peierls <tim at peierls.net> wrote:
> On Sun, Nov 30, 2014 at 11:03 AM, Doug Lea <dl at cs.oswego.edu> wrote:
>>
>> On 11/30/2014 09:30 AM, Tim Peierls wrote:
>>>
>>>
>>> Confusing, because of the inherited CompletionStage doc: The type of
>>> "this" and
>>> the return type promised by the doc are both referred to as "stage" when
>>> in fact
>>> both are specifically CompletableFuture. That's imprecise, not wrong, but
>>> it
>>> makes the reader stumble right off.
>>
>>
>> OK, but we do this uniformly in java.util/j.u.c.
>>
>> For example, see the many
>> mentions of "this collection" in Collection implementations.
>
>
>
> Well... Two seconds of looking and I found an inconsistency: type parameter
> E for Set is "type of elements maintained by this set" and for Queue is
> "type of elements held in this collection" (compare E in List, SortedSet,
> Deque, ...). Further brief manual scan picked up no other instances of "this
> collection" in the docs for commonly used Collection subtypes in j.u.
>
> And just because we do it, doesn't mean it's a good thing. In most cases we
> are getting away with it, but read on for my reasoning about when it becomes
> inappropriate.

I actually made an effort many years ago to make the javadoc for
collection classes better by changing "this collection" to "this set",
etc.  The most readable is for both Set and HashSet to use "this set",
I think.  For CompletableFuture, it is better to change occurrences of
"this stage".  Readability trumps maintainability for core
libraries.... except that here the amount of copy-paste that would be
required is unprecedented ... so I'm hesitating ....

But while we're thinking about that, do we have agreement that the
following is progress?

Index: AbstractQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/AbstractQueue.java,v
retrieving revision 1.38
diff -u -U 0 -r1.38 AbstractQueue.java
--- AbstractQueue.java 16 Jan 2013 01:59:47 -0000 1.38
+++ AbstractQueue.java 1 Dec 2014 18:21:02 -0000
@@ -33 +33 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: ArrayDeque.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/ArrayDeque.java,v
retrieving revision 1.59
diff -u -U 0 -r1.59 ArrayDeque.java
--- ArrayDeque.java 23 Nov 2014 18:06:50 -0000 1.59
+++ ArrayDeque.java 1 Dec 2014 18:21:02 -0000
@@ -56 +56 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this deque
Index: Deque.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/Deque.java,v
retrieving revision 1.29
diff -u -U 0 -r1.29 Deque.java
--- Deque.java 23 Nov 2014 18:46:47 -0000 1.29
+++ Deque.java 1 Dec 2014 18:21:02 -0000
@@ -162 +162 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this deque
Index: PriorityQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/PriorityQueue.java,v
retrieving revision 1.100
diff -u -U 0 -r1.100 PriorityQueue.java
--- PriorityQueue.java 29 Aug 2014 21:42:37 -0000 1.100
+++ PriorityQueue.java 1 Dec 2014 18:21:03 -0000
@@ -80 +80 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: Queue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/Queue.java,v
retrieving revision 1.41
diff -u -U 0 -r1.41 Queue.java
--- Queue.java 12 Nov 2013 23:23:05 -0000 1.41
+++ Queue.java 1 Dec 2014 18:21:03 -0000
@@ -113 +113 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/ArrayBlockingQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/ArrayBlockingQueue.java,v
retrieving revision 1.108
diff -u -U 0 -r1.108 ArrayBlockingQueue.java
--- concurrent/ArrayBlockingQueue.java 11 Apr 2014 21:15:44 -0000 1.108
+++ concurrent/ArrayBlockingQueue.java 1 Dec 2014 18:21:03 -0000
@@ -53 +53 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/BlockingDeque.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/BlockingDeque.java,v
retrieving revision 1.27
diff -u -U 0 -r1.27 BlockingDeque.java
--- concurrent/BlockingDeque.java 12 Nov 2013 23:23:05 -0000 1.27
+++ concurrent/BlockingDeque.java 1 Dec 2014 18:21:03 -0000
@@ -169 +169 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this deque
Index: concurrent/BlockingQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/BlockingQueue.java,v
retrieving revision 1.53
diff -u -U 0 -r1.53 BlockingQueue.java
--- concurrent/BlockingQueue.java 12 Nov 2013 23:23:05 -0000 1.53
+++ concurrent/BlockingQueue.java 1 Dec 2014 18:21:03 -0000
@@ -149 +149 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/ConcurrentLinkedDeque.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentLinkedDeque.java,v
retrieving revision 1.54
diff -u -U 0 -r1.54 ConcurrentLinkedDeque.java
--- concurrent/ConcurrentLinkedDeque.java 23 Nov 2014 21:39:30 -0000 1.54
+++ concurrent/ConcurrentLinkedDeque.java 1 Dec 2014 18:21:04 -0000
@@ -63 +63 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this deque
Index: concurrent/ConcurrentLinkedQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentLinkedQueue.java,v
retrieving revision 1.104
diff -u -U 0 -r1.104 ConcurrentLinkedQueue.java
--- concurrent/ConcurrentLinkedQueue.java 23 Nov 2014 18:20:26 -0000 1.104
+++ concurrent/ConcurrentLinkedQueue.java 1 Dec 2014 18:21:04 -0000
@@ -77 +77 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/CopyOnWriteArrayList.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/CopyOnWriteArrayList.java,v
retrieving revision 1.117
diff -u -U 0 -r1.117 CopyOnWriteArrayList.java
--- concurrent/CopyOnWriteArrayList.java 23 Nov 2014 21:40:08 -0000 1.117
+++ concurrent/CopyOnWriteArrayList.java 1 Dec 2014 18:21:05 -0000
@@ -71 +71 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this list
Index: concurrent/CopyOnWriteArraySet.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/CopyOnWriteArraySet.java,v
retrieving revision 1.59
diff -u -U 0 -r1.59 CopyOnWriteArraySet.java
--- concurrent/CopyOnWriteArraySet.java 23 Nov 2014 21:40:08 -0000 1.59
+++ concurrent/CopyOnWriteArraySet.java 1 Dec 2014 18:21:05 -0000
@@ -66 +66 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this set
Index: concurrent/DelayQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/DelayQueue.java,v
retrieving revision 1.66
diff -u -U 0 -r1.66 DelayQueue.java
--- concurrent/DelayQueue.java 11 Apr 2014 21:15:44 -0000 1.66
+++ concurrent/DelayQueue.java 1 Dec 2014 18:21:05 -0000
@@ -39 +39 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/LinkedBlockingDeque.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/LinkedBlockingDeque.java,v
retrieving revision 1.51
diff -u -U 0 -r1.51 LinkedBlockingDeque.java
--- concurrent/LinkedBlockingDeque.java 8 Aug 2013 20:12:10 -0000 1.51
+++ concurrent/LinkedBlockingDeque.java 1 Dec 2014 18:21:05 -0000
@@ -48 +48 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this deque
Index: concurrent/LinkedBlockingQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/LinkedBlockingQueue.java,v
retrieving revision 1.87
diff -u -U 0 -r1.87 LinkedBlockingQueue.java
--- concurrent/LinkedBlockingQueue.java 8 Aug 2013 20:12:10 -0000 1.87
+++ concurrent/LinkedBlockingQueue.java 1 Dec 2014 18:21:05 -0000
@@ -51 +51 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/LinkedTransferQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/LinkedTransferQueue.java,v
retrieving revision 1.74
diff -u -U 0 -r1.74 LinkedTransferQueue.java
--- concurrent/LinkedTransferQueue.java 23 Nov 2014 17:44:51 -0000 1.74
+++ concurrent/LinkedTransferQueue.java 1 Dec 2014 18:21:05 -0000
@@ -60 +60 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/PriorityBlockingQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/PriorityBlockingQueue.java,v
retrieving revision 1.103
diff -u -U 0 -r1.103 PriorityBlockingQueue.java
--- concurrent/PriorityBlockingQueue.java 8 Aug 2013 20:12:10 -0000 1.103
+++ concurrent/PriorityBlockingQueue.java 1 Dec 2014 18:21:05 -0000
@@ -79 +79 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/SynchronousQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/SynchronousQueue.java,v
retrieving revision 1.105
diff -u -U 0 -r1.105 SynchronousQueue.java
--- concurrent/SynchronousQueue.java 29 Nov 2014 03:03:14 -0000 1.105
+++ concurrent/SynchronousQueue.java 1 Dec 2014 18:21:05 -0000
@@ -55 +55 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue
Index: concurrent/TransferQueue.java
===================================================================
RCS file: /export/home/jsr166/jsr166/jsr166/src/main/java/util/concurrent/TransferQueue.java,v
retrieving revision 1.5
diff -u -U 0 -r1.5 TransferQueue.java
--- concurrent/TransferQueue.java 15 Mar 2011 19:47:04 -0000 1.5
+++ concurrent/TransferQueue.java 1 Dec 2014 18:21:05 -0000
@@ -37 +37 @@
- * @param <E> the type of elements held in this collection
+ * @param <E> the type of elements held in this queue


More information about the Concurrency-interest mailing list