RFR: 8266571: Sequenced Collections [v7]

[Pavel Rappo]

On Thu, 20 Apr 2023 16:19:05 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>>> 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.

I note that other methods might have similar issues. For example, `NullPointerException` in `addFirst` and `addLast`.

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

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