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

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:

     <p>
     <pre>

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  *

DocRootTree:

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

DocTypeTree:
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>}.

EntityTree:
Maybe remove the "misleading" spaces in the examples?

General:

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.

DocSourcePositions:57,89
replace `CompilationUnit` with `compilation unit`

DocTreeFactory:112
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?

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

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

DocCommentParser:
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.

WriterFactory:135
Trailing period.

BaseTaglet
Yay for removing redundant doc comments from overridden methods!

toolkit/taglets/Taglet.java
41,143:
If you think "tag" refers to instances in doc comments, the original was 
correct
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>