On Tue, 9 Aug 2022 05:51:17 GMT, Alan Bateman <al...@openjdk.org> wrote:
>> The whole paragraph is about thread termination, so I don't think we need to >> say "terminate" again in the last sentence. We could mention isAlive or the >> TERMINATED state, but that brings in Thread.State which which require a >> discussion of the thread's life cycle. >> >> The "join" sentence was kind of tacked on to the end of a paragraph in the >> original text; Alex suggested that I separate it into its own paragraph when >> we were working on the "termination" paragraph. Alex doesn't mind >> single-sentence paragraphs, which isn't my preference. But tacking the >> "join" sentence onto the end of the "termination" paragraph actually doesn't >> make any sense. Termination is something that happens to _this_ thread. The >> join method is called from _another_ thread, and this implicit shift of >> viewpoint would weaken the paragraph. >> >> Frankly I think there needs to be a separate editorial pass over the Thread >> docs. I know they were just rewritten in JDK 19, but there are some odd >> things about it. The Thread.State life cycle isn't explained and isn't >> referenced by methods such as start() and isAlive(). Also, various mentions >> of uncaught exception handling talk about a thread's abrupt termination. >> There isn't any such thing; a _method_ can complete normally or abruptly, >> and when a thread's run() method completes either way, the thread simply >> terminates. > > Thread.State was added (in Java 5) for monitoring and management purposes, > it's not an API that most libraries or programs would use. It could be > introduced in the class description and referenced from other APIs that > change/test the state but it would encourage use beyond the original intent. What you have is okay although I would have preferred if the sentence on the join method was in the previous paragraph rather as it fits with termination. ------------- PR: https://git.openjdk.org/jdk/pull/9437
