RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v4]

[Pavel Rappo]

On Wed, 18 May 2022 18:43:44 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review the code and tests to add support for a new `@spec url title` tag to javadoc.  Note, this does not include any changes to API doc comments to use the new tag in JDK API documentation; that will come later.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   address review feedback

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java line 302:

> 300:      * @since 19
> 301:      */
> 302:     default R visitSpec(SpecTree node, P p) {

Nit: this method breaks the alphabetic order of visitor methods. Although `visitOther` also breaks it, we should not address it in this PR.

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 515:

> 513:      * {@inheritDoc}
> 514:      *
> 515:      * @param node {@inheritDoc}

There's something wrong with the `@implSpec` tags in this and the immediately following two methods. Might be an artifact of the patch.

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1533:

> 1531:                 public DCTree parse(int pos) throws ParseException {
> 1532:                     skipWhitespace();
> 1533:                     DCText url = inlineWord();

Nit: call it `uri` for consistency.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 432:

> 430: doclet.extSpec.url.title=\
> 431:     url: {0}, title: "{1}"
> 432: 

Use `uri` in all 4 resources?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java line 1098:

> 1096: 
> 1097:     /**
> 1098:      * Argument for command-line option {@code --spec-base-URI}.

I think the option is lower-cased `--spec-base-uri`.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SpecTaglet.java line 2:

> 1: /*
> 2:  * Copyright (c) 2001, 2022, Oracle and/or its affiliates. All rights reserved.

2001?

test/langtools/tools/javac/diags/examples/NoTitle.java line 2:

> 1: /*
> 2:  * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.

2012? Is it an old file from the previous incarnation of the `@spec` tag?

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

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