RFR: JDK-8245058: improve presentation of annotations for modules and packages

[Jonathan Gibbons]

On Fri, 30 Oct 2020 20:11:49 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> This PR adds a dedicated signature to module and package overview pages and moves all code for generating signatures to a new `doclets.formats.html.Signatures` utility class. The `Signatures` class contains two public static methods for module and package signatures as well as two inner classes for type and member signatures. 
> 
> Signatures are rendered as `<div>` elements with top level CSS classes that identify the kind of signature: `module-signature`, `package-signature`, `type-signature` and `member-signature`. Signature components are rendered as `<span>` elements with CSS classes that identify the component, e.g.: `modifiers`, `annotations`, `element-name`, `exceptions`. 
> 
> As a side benefit, this PR reduces the number of methods in `HtmlDocletWriter` used to generate annotation information.

Generally, very nice to see this continuation of the improvements to handle signatures.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java line 300:

> 298:             Set<TypeElement> subclasses = classtree.directSubClasses(typeElement, false);
> 299:             if (!subclasses.isEmpty()) {
> 300:                 HtmlTree dl = HtmlTree.DL(HtmlStyle.notes);

I'm surprised this has gone; is this intentional?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1681:

> 1679: 
> 1680:     /**
> 1681:      * Return a content tree containing the  annotation types for the given Element.

(minor) either put type names (Element) in code font or use English equivalent (element).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1686:

> 1684:      * @param lineBreak if true add new line between each member value
> 1685:      * @return the documentation tree to which the annotation info will be
> 1686:      *        added

The method is `getAnnotationInfo` so it seems strange/confusing to return an object to which the info _will be_ added (future tense.)  I'm surprised it's not a documentation tree containing the annotation info.
Is this a hangover from the old code?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1693:

> 1691: 
> 1692:     /**
> 1693:      * Return a content tree containing the annotation types for the given element.

`Returns`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1718:

> 1716:      *
> 1717:      * @param descList a list of annotation mirrors.
> 1718:      * @param lineBreak if true, add new line between each member value.

Funny typo ;-)  Good catch!

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 531:

> 529:     //<editor-fold desc="member signature">
> 530:     //
> 531:     // The following constants are used for the components of a signature of an element

Two lines earlier, line 529, change `member signature` to `signatures`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 490:

> 488: .deprecated-content {
> 489:     margin:0;
> 490:     padding:10px 0;

Yay! Good improvement.

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

Marked as reviewed by jjg (Reviewer).

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