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

[Hannes Wallnöfer]

On Thu, 26 Nov 2020 18:04:49 GMT, Jonathan Gibbons <jjg 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.
>
> 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?

Indeed, the method returns the fully rendered content. I'm fixing this in a follow-up commit (along with other issues).

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

Good catch...

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

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