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

cowwoc cowwoc at bbs.darktech.org
Mon Dec 1 13:28:34 EST 2014


+1 that readability trumps maintainability. "Written a few times, read 
many more times" :)

Gili

On 01/12/2014 1:26 PM, Martin Buchholz-3 [via JSR166 Concurrency] wrote:
> On Sun, Nov 30, 2014 at 8:59 AM, Tim Peierls <[hidden email] 
> </user/SendEmail.jtp?type=node&node=11532&i=0>> wrote:
>
> > On Sun, Nov 30, 2014 at 11:03 AM, Doug Lea <[hidden email] 
> </user/SendEmail.jtp?type=node&node=11532&i=1>> 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
> _______________________________________________
> Concurrency-interest mailing list
> [hidden email] </user/SendEmail.jtp?type=node&node=11532&i=2>
> http://cs.oswego.edu/mailman/listinfo/concurrency-interest
>
>
> ------------------------------------------------------------------------
> If you reply to this email, your message will be added to the 
> discussion below:
> http://jsr166-concurrency.10961.n7.nabble.com/Please-clarify-Javadoc-of-CompletableFuture-thenCompose-tp11504p11532.html 
>
> To unsubscribe from Please clarify Javadoc of 
> CompletableFuture.thenCompose(), click here 
> <http://jsr166-concurrency.10961.n7.nabble.com/template/NamlServlet.jtp?macro=unsubscribe_by_code&node=11504&code=Y293d29jQGJicy5kYXJrdGVjaC5vcmd8MTE1MDR8MTU3NDMyMTI0Nw==>.
> NAML 
> <http://jsr166-concurrency.10961.n7.nabble.com/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml> 
>





--
View this message in context: http://jsr166-concurrency.10961.n7.nabble.com/Please-clarify-Javadoc-of-CompletableFuture-thenCompose-tp11504p11533.html
Sent from the JSR166 Concurrency mailing list archive at Nabble.com.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cs.oswego.edu/pipermail/concurrency-interest/attachments/20141201/374b6860/attachment-0001.html>


More information about the Concurrency-interest mailing list