On Thu, 20 Apr 2023 16:19:05 GMT, Stuart Marks <sma...@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
