RFR: JDK-8252712: move doclint to jdk.javadoc module [v2]

[Jonathan Gibbons]

On Tue, 22 Sep 2020 11:28:04 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now
>> contains four commits:
>>  - Merge master
>>  - Merge
>>  - move doclint to jdk.javadoc module
>>  - add DocTrees.getCharacters(EntityTree)
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1265:
> 
>> 1263:
>> 1264:         if (name != null) {
>> 1265:             jdk.javadoc.internal.doclint.HtmlTag htmlTag = jdk.javadoc.internal.doclint.HtmlTag.get(name);
> 
> Is there a reason not to import the HtmlTag class?

There is (have always been) two different versions of `HtmlTag`, albeit for different purposes, and up to now, in
different modules. The one in `doclint` is more for input, the one in `doclets/formats/html/markup` is more focussed on
output. Use sites like this are where the two domains meet and so both need to be in scope. Hence at least one needs to
be fully-qualified and not imported. IIRC, the policy is that the `doclets/formats/html/markup` version is more widely
used throughout the standard docket and gets to be important, leaving the `doclint` one to be fully-qualified.

At least now they both in the same module, which increases the chance of reducing them to one copy, perhaps by
replacing some of the enum-member methods with separate switch-based utility methods that locally provide the requisite
functionality.  That being said, I still don't see a good way to merge them, meaning, I don't see a good place to put a
merged copy. One possibility I have been thinking about is moving the HTML-only parts of `doclets/formats/html/markup`
to a separate sharable package such as `jdk.javadoc.internal.html` where it could be used by both doclint and the
standard docket. IIRC, the one outlier in `formats.html.markup` is the `Links` class, which  I would migrate up to
`doclets.formats.html` (i.e. out of the `markup` subpackage.)

Separate but somewhat related, the `formats/html/markup` classes have been a good pattern for other tools that generate
HTML, such as doccheck and similar reporting tools.

> src/jdk.compiler/share/classes/com/sun/tools/doclint/DocLint.java line 1:
> 
>> 1: package com.sun.tools.doclint;
> 
> Why is there no copyright header in this file?

Oops, will fix!

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java line 2:
> 
>> 1: /*
>> 2:  * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
> 
> Copyright year should be updated

I'll try and get into a new habit of updating copyrights earlier. Personally, I think these updates are unnecessary
noise in a review, and I would usually update files after the review but before pushing the changes. I guess that is
not so easy anymore, since I don't want to affect "Reviewed" status by committing copyright year changes.

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

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