RFR: JDK-8263043: Add test to verify order of tag output

[Pavel Rappo]

On Thu, 4 Mar 2021 21:12:15 GMT, Jonathan Gibbons <jjg at 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