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