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

[Hannes Wallnöfer]

On Tue, 22 Sep 2020 20:28:49 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

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

The HtmlTag in `doclets/formats/html/markup` seems to have gone. Maybe it has been renamed?

>> src/jdk.compiler/share/classes/jdk/internal/shellsupport/doc/JavadocFormatter.java line 127:
>> 
>>> 125:     }
>>> 126:
>>> 127:     enum HtmlTag {
>> 
>> What was the criterion for choosing this subset of HtmlTag values? It seems the only ones actually used by this class
>> are HTML, TABLE, TH, and LI.
>
> See the `startElement` method, starting at about line 269.
> The intent is that this enum is minimal, just for the needs of this class.

Oops, not sure how I missed that.

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

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