RFR: 8266571: Sequenced Collections [v7]

[Stuart Marks]

On Thu, 20 Apr 2023 09:03:03 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> @pavelrappo Arrrrggh.
>> 
>>> I guess, this PR has converged enough for us to discuss some trivial stuff; so here it goes.
>> 
>> All this "trivial" stuff is generating a lot of work! :-) Well, no big deal, Joe D still has more CSR comments coming.
>> 
>> I didn't know about the need to specify `@throws` in order to generate the throws-clauses in the docs. Ah, well, turns out it wasn't THAT bad to run through the hierarchy and check all the inherited methods. Done.
>> 
>> As an aside, I note that some methods such as ArrayList.addFirst/addLast had this javadoc:
>> 
>>     /**
>>      * @inheritDoc
>>      */
>> 
>> It didn't appear at all in the javadoc output, I guess because of `--override-methods=summary`. Not surprising in isolation, but it seemed strange because the getX and removeX methods were in the detail section but the addX methods seemed "missing". Is there a way to inherit the doc from a superclass but force a particular method to have its details included? It's kind of moot because these are also missing a `@since` tag, and adding that did cause the method detail to be included. Seems like the summary/detail stuff still needs some things to be worked out.
>
>> I didn't know about the need to specify `@throws` in order to generate the throws-clauses in the docs. 
> 
> You need to explicitly inherit `@throws` only for exceptions that aren't mentioned in the `throws` clause.
> 
>> As an aside, I note that some methods such as ArrayList.addFirst/addLast had this javadoc:
>> 
>> ```
>> /**
>>  * @inheritDoc
>>  */
>> ```
>> 
>> It didn't appear at all in the javadoc output, I guess because of `--override-methods=summary`.
> 
> Correct: it shouldn't have appeared in "Method Details" because of that option. But if it didn't appear at all (i.e. not even in the "Method Summary / Methods declared in ..." table at the top of the page), it's a bug.
> 
>> Is there a way to inherit the doc from a superclass but force a particular method to have its details included? It's kind of moot because these are also missing a `@since` tag, and adding that did cause the method detail to be included.
> 
> Other than to add to the inherited documentation? Not that I know of. Yes, adding a `@since` tag will cause the method detail to appear.

Oh, oops, I was mistaken to say "It didn't appear at all in the javadoc output." It did appear in the Method Summary, but not in the Method Details. The behavior is thus as expected. However, it still seems like there's something "off" about this situation. As a javadoc author it's hard to predict what will happen. Maybe more control is necessary. In addition, from the editorial standpoint of the specification, we also need to figure out when something should appear in the Summary and when it should appear in the Detail. Actually we should figure that out first, use it to drive the appropriate mechanisms in the javadoc tool, and then adjust the doc comments themselves as necessary.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/7387#discussion_r1172823558