Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8199501

Improve documentation of CompletableFuture, CompletionStage

    Details

      Description

      A DESCRIPTION OF THE REQUEST :
      Please revise the documentation of CompletableFuture and CompletionStage. As a native English speaker, I am having a very hard time understanding the descriptions. I can't imagine what non-native English speakers must be going through.

      Here is the description given by CompletableFuture.exceptionally():

      ------
      Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of the exception triggering this CompletableFuture's completion when it completes exceptionally; otherwise, if this CompletableFuture completes normally, then the returned CompletableFuture also completes normally with the same value. Note: More flexible versions of this functionality are available using methods whenComplete and handle.
      ------

      Please unpack this paragraph in terms of:

      * The previous CompletionFuture (previous)
      * The value returned by previous (previous.value)
      * The exception thrown by previous (previous.exception)
      * The value returned by the returned CompletionFuture (next.value)
      * The exception thrown by the returned CompletionFuture (next.exception)
      * The function passed to result (whatever the parameter name is, in this case "fn")

      I would expect something along the lines of:

      "Given this CompletableFuture (previous), returns a new CompletableFuture (next) that completes normally with previous.value when previous completes normally, and completes exceptionally with any exception thrown by the {@code fn}"

      Please try avoid intermixing "this" as a variable with the prose form of "this" as it gets very confusing very quickly. This is why I favor the use of "current" or "previous" in the above description.

      JUSTIFICATION :
      Improved readability, reduced number of bugs in user code.


        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              webbuggrp Webbug Group
            • Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

              • Created:
                Updated: