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

[Jonathan Gibbons]

On Fri, 5 Mar 2021 11:21:20 GMT, Pavel Rappo <prappo 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.
>
> 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.

oops. will fix

> 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

Hmm.  Noted.  At a minimum this will be good for the man page updates. I'll see if we can update command-line help in a reasonable way as well.

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

Hmmm ...
Actually, my initial version of the code _did_ include `@author`, but not `@version`.  But, it didn't work as expected ... because neither are actually supported on methods, and so they do not appear in the output.  See https://docs.oracle.com/en/java/javase/15/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used

So, if you really think we should test these as well, we will have to extend the test to include comments on a class or interface declaration.

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

PR: https://git.openjdk.java.net/jdk/pull/2835