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

[Jonathan Gibbons]

On Tue, 3 May 2022 12:40:42 GMT, Pavel Rappo <prappo 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.
>
> src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 340:
> 
>> 338:     SnippetTree newSnippetTree(List<? extends DocTree> attributes, TextTree text);
>> 339: 
>> 340:     /**
> 
> Similar comment to that of DocTreeVisitor: consider adhering to the file style.

I see there is a missing `@since` tag, which I'll fix.
I'd prefer to leave the extra whitespace for now, and maybe cleanup the style of the other comments later.

> src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 512:
> 
>> 510:     }
>> 511: 
>> 512:     /**
> 
> Similar comment on the file style.

I'll adjust the order of the tags.

Aside: we should have a guideline somewhere on the recommended order of block tags in a comment,

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

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