RFR: JDK-8263043: Add test to verify order of tag output
Pavel Rappo
prappo at openjdk.java.net
Fri Mar 5 16:02:15 UTC 2021
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
More information about the javadoc-dev
mailing list