RFR [16] 8251550: Clean up jdk.javadoc and the related parts of jdk.compiler

Jonathan Gibbons jonathan.gibbons at oracle.com
Fri Aug 14 16:49:09 UTC 2020

Good cleanup.

Some systemic changes needed. Details below.

-- Jon

On 8/13/20 11:48 AM, Pavel Rappo wrote:
> Hello,
> Please review the below change for https://bugs.openjdk.java.net/browse/JDK-8251550
>    http://cr.openjdk.java.net/~prappo/8251550/webrev.00/
> This represents squashed commits that have accumulated in my git branch. Since the changeset has started to look dangerously big, I decided not to wait until we finish the migration to Git and GitHub, and push it sooner. The less the others have to merge, the better.
> -Pavel

Some of the doctree changes contain this sequence:


That will trigger a doccheck warning for a redundant <p> tag.

Since you're improving the doc comments for the DocTree nodes, it would 
be nice to use <i>...</i> or (better) <var>,,,</var> around the 
variables in the templates. For example:

34 * <pre>
35 * @author <var>name-text</var>
36 * </pre>
   37  *


I think you need {@literal ...} on line 33.

As an enhancement, given that the tools only support HTML 5 these days, 
It might be helpful to give the specific text for an HTML 5 document

32 * <pre>
   33  *    <!doctype text>
34 * </pre>

     + * For HTML5 documents, the correct form is  {@code <!doctype html>}.

Maybe remove the "misleading" spaces in the examples?


Thinking aloud, for a future update when we have the `{@spec}` tag. In 
the introductory sentence for each tag, replace the use of `{@code}` by 
`{@spec}` linking to the right place in the doc-comment tag 
specification. I guess for many, it's not necessary, but the idea came 
to mind reading IndexTree, where more information may be helpful. That 
being said, additional info belongs in the tag spec, not the tree node spec.

replace `CompilationUnit` with `compilation unit`

We are inconsistent about whether to use `{..}` for inline tags, which 
will be worse when we add our first bimodal standard tag, `@return`, but 
using `{...}` for `{@deprecated}` is definitely wrong

General: (question)
Does a trailing space inside `{@code something }` cause extra whitespace 
in the rendered HTML?

More un-code-d type names. Follow existing conventions for either using 
`{@code...}` or the descriptive equivalent (e.g. "tree path")

replace "The" by "the"
remove package name from TypeMirror, and use @code for that and ErrorType

avoid Latin abbreviations; use "for example, such as"
1103: another candidate for `{@spec}` !!

Pretty: removing import
In general, this is a dangerous edit; throughout javac, you will see 
imports of javac.util.List in preference to java.util.List. I assume you 
have compiled and run the tests, to validate this change.

Trailing period.

Yay for removing redundant doc comments from overridden methods!

If you think "tag" refers to instances in doc comments, the original was 
If you think "tag" refers to the class of the instances, the new text 
should use "the block tag"
142: consider remove "all" from end of line

-- Jon

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20200814/dfdd7534/attachment.htm>

More information about the compiler-dev mailing list