RFR: 8266571: Sequenced Collections [v7]

[Pavel Rappo]

On Thu, 20 Apr 2023 04:13:57 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.

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

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