On Thu, 4 Mar 2021 21:12:15 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
> Please review a new test to verify that the output of block tags is generated
> in the expected order.
>
> The code in the standard doclet to generate the output is the same for all
> use sites (modules, packages, class, members) and so just the richest site is
> tested.
>
> The test checks that tags appear in the expected order by default, but can be
> reordered in a couple of different ways.
Marked as reviewed by prappo (Reviewer).
test/langtools/jdk/javadoc/doclet/testTagOrder/TestTagOrder.java line 50:
> 48: * Tests the order of the output of block tags in the generated output.
> 49: * There is a default order, embodies in the order of declaration of tags
> in
> 50: * {@code Tagl;etManager}, but this can be overridden on the command line
> by
Typo: "Tagl;etManager". Grammar: "embodies" does not seem to fit into the
context.
test/langtools/jdk/javadoc/doclet/testTagOrder/TestTagOrder.java line 51:
> 49: * There is a default order, embodies in the order of declaration of tags
> in
> 50: * {@code Tagl;etManager}, but this can be overridden on the command line
> by
> 51: * specifying {@code -tag} options in the desired order.
I didn't know you could reorder standard tags using that option for custom
tags. Although I found the relevant [section in the
manual](https://docs.oracle.com/en/java/javase/15/javadoc/javadoc-command.html#GUID-9A64CB90-0CC9-4BC3-B3B1-6EF83C89AA7D__GUID-92C9DDDE-CBA0-4710-8467-9AF11931D4AE),
we should separately consider improving output from `javadoc -h` to reflect
such use of `-tag`:
-tag <name>:<locations>:<header>
Specify single argument custom tags
test/langtools/jdk/javadoc/doclet/testTagOrder/TestTagOrder.java line 76:
> 74: * @throws IllegalArgumentException well, never
> 75: * @since 1.0
> 76: * @see <a href="http://example.com";>example</a>
Consider adding `@version` and `@author` standard tags to this test. Although
JDK API documentation does not include those, API documentation of other
projects might. Adding those tags will improve coverage.
-------------
PR: https://git.openjdk.java.net/jdk/pull/2835
