RFR: StructuredTaskScope Javadoc: consistently use the phrase "contained in the task scope" [v2]

[Alan Bateman]

On Sun, 13 Nov 2022 15:15:56 GMT, Anthony Vanelverdinghe <duke at openjdk.org> wrote:

>> The class-level Javadoc of StructuredTaskScope contains the following:
>> 
>>> The phrase "threads contained in the task scope" in method descriptions means threads started in the task scope or descendant scopes.
>> 
>> However, the method-level Javadoc sometimes uses slightly different wordings.
>> This PR updates the Javadoc to consistently use the phrase "contained in the task scope" (and fixes an unrelated typo).
>> 
>> PS: I'll need help from someone to create a JBS issue & sponsor this PR
>
> Anthony Vanelverdinghe has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Revert incorrect change

src/jdk.incubator.concurrent/share/classes/jdk/incubator/concurrent/StructuredTaskScope.java line 508:

> 506:     /**
> 507:      * Wait for all threads to finish or the task scope to shut down. This method waits
> 508:      * until all threads contained in the task scope finish execution (of both task and

I checked the usages of "started in" and "contained in" in the javadoc and I think they are consistently used. The phrase "contained in" is introduced in the context of confinement and then used in the description and exceptions for methods that are confined to threads in the tree. In the case of the join methods, they wait for the threads started directly in the task scope and so using "started in" is correct. Waiting for the threads started in the task scope does imply waiting indirectly for all threads in the tree and we could potentially expand the javadoc on this point.

-------------

PR: https://git.openjdk.org/loom/pull/194