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.