8245058: improve presentation of annotations for modules and packages

Reviewed-by: jjg

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java

@@ -160,7 +160,7 @@ protected void addParam(ExecutableElement member, VariableElement param, TypeMir
      */
     protected void addReceiverAnnotations(ExecutableElement member, TypeMirror rcvrType,
             List<? extends AnnotationMirror> annotationMirrors, Content tree) {
-        writer.addReceiverAnnotationInfo(member, rcvrType, annotationMirrors, tree);
+        tree.add(writer.getAnnotationInfo(member.getReceiverType().getAnnotationMirrors(), false));
         tree.add(Entity.NO_BREAK_SPACE);
         tree.add(utils.getTypeName(rcvrType, false));
         LinkInfoImpl linkInfo = new LinkInfoImpl(configuration, RECEIVER_TYPE, rcvrType);
@@ -212,11 +212,11 @@ protected Content getParameters(ExecutableElement member, boolean includeAnnotat
 
             if (param.getKind() != ElementKind.INSTANCE_INIT) {
                 if (includeAnnotations) {
-                    boolean foundAnnotations =
-                            writer.addAnnotationInfo(param, paramTree);
-                    if (foundAnnotations) {
-                        paramTree.add(DocletConstants.NL);
-                        paramTree.add(" ");
+                    Content annotationInfo = writer.getAnnotationInfo(param, false);
+                    if (!annotationInfo.isEmpty()) {
+                        paramTree.add(annotationInfo)
+                                .add(DocletConstants.NL)
+                                .add(" ");
                     }
                 }
                 addParam(member, param, paramType,
@@ -231,12 +231,11 @@ protected Content getParameters(ExecutableElement member, boolean includeAnnotat
             paramTree.add(" ");
 
             if (includeAnnotations) {
-                boolean foundAnnotations =
-                        writer.addAnnotationInfo(parameters.get(i),
-                        paramTree);
-                if (foundAnnotations) {
-                    paramTree.add(DocletConstants.NL);
-                    paramTree.add(" ");
+                Content annotationInfo = writer.getAnnotationInfo(parameters.get(i), false);
+                if (!annotationInfo.isEmpty()) {
+                    paramTree.add(annotationInfo)
+                            .add(DocletConstants.NL)
+                            .add(" ");
                 }
             }
             addParam(member, parameters.get(i), instMeth.getParameterTypes().get(i),

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java

@@ -421,235 +421,4 @@ public Content getMemberListItem(Content memberTree) {
         return writer.getMemberListItem(memberTree);
     }
 
-    /**
-     * A content builder for member signatures.
-     */
-    class MemberSignature {
-
-        private final Element element;
-        private Content typeParameters;
-        private Content returnType;
-        private Content parameters;
-        private Content exceptions;
-
-        // Threshold for length of type parameters before switching from inline to block representation.
-        private static final int TYPE_PARAMS_MAX_INLINE_LENGTH = 50;
-
-        // Threshold for combined length of modifiers, type params and return type before breaking
-        // it up with a line break before the return type.
-        private static final int RETURN_TYPE_MAX_LINE_LENGTH = 50;
-
-        /**
-         * Creates a new member signature builder.
-         *
-         * @param element the element for which to create a signature
-         */
-        MemberSignature(Element element) {
-            this.element = element;
-        }
-
-        /**
-         * Adds the type parameters for an executable member.
-         *
-         * @param typeParameters the content tree containing the type parameters to add.
-         *
-         * @return this instance
-         */
-        MemberSignature addTypeParameters(Content typeParameters) {
-            this.typeParameters = typeParameters;
-            return this;
-        }
-
-        /**
-         * Adds the return type for an executable member.
-         *
-         * @param returnType the content tree containing the return type to add.
-         *
-         * @return this instance
-         */
-        MemberSignature addReturnType(Content returnType) {
-            this.returnType = returnType;
-            return this;
-        }
-
-        /**
-         * Adds the type information for a non-executable member.
-         *
-         * @param type the type of the member.
-         *
-         * @return this instance
-         */
-        MemberSignature addType(TypeMirror type) {
-            this.returnType = writer.getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.MEMBER, type));
-            return this;
-        }
-
-        /**
-         * Adds the parameter information of an executable member.
-         *
-         * @param paramTree the content tree containing the parameter information.
-         *
-         * @return this instance
-         */
-        MemberSignature addParameters(Content paramTree) {
-            this.parameters = paramTree;
-            return this;
-        }
-
-        /**
-         * Adds the exception information of an executable member.
-         *
-         * @param exceptionTree the content tree containing the exception information
-         *
-         * @return this instance
-         */
-        MemberSignature addExceptions(Content exceptionTree) {
-            this.exceptions = exceptionTree;
-            return this;
-        }
-
-        /**
-         * Returns an HTML tree containing the member signature.
-         *
-         * @return an HTML tree containing the member signature
-         */
-        Content toContent() {
-            Content content = new ContentBuilder();
-            // Position of last line separator.
-            int lastLineSeparator = 0;
-
-            // Annotations
-            Content annotationInfo = writer.getAnnotationInfo(element.getAnnotationMirrors(), true);
-            if (!annotationInfo.isEmpty()) {
-                content.add(HtmlTree.SPAN(HtmlStyle.annotations, annotationInfo));
-                lastLineSeparator = content.charCount();
-            }
-
-            // Modifiers
-            appendModifiers(content);
-
-            // Type parameters
-            if (typeParameters != null && !typeParameters.isEmpty()) {
-                lastLineSeparator = appendTypeParameters(content, lastLineSeparator);
-            }
-
-            // Return type
-            if (returnType != null) {
-                content.add(HtmlTree.SPAN(HtmlStyle.returnType, returnType));
-                content.add(Entity.NO_BREAK_SPACE);
-            }
-
-            // Name
-            HtmlTree nameSpan = new HtmlTree(TagName.SPAN);
-            nameSpan.setStyle(HtmlStyle.memberName);
-            if (options.linkSource()) {
-                Content name = new StringContent(name(element));
-                writer.addSrcLink(element, name, nameSpan);
-            } else {
-                nameSpan.add(name(element));
-            }
-            content.add(nameSpan);
-
-            // Parameters and exceptions
-            if (parameters != null) {
-                appendParametersAndExceptions(content, lastLineSeparator);
-            }
-
-            return HtmlTree.DIV(HtmlStyle.memberSignature, content);
-        }
-
-        /**
-         * Adds the modifier for the member. The modifiers are ordered as specified
-         * by <em>The Java Language Specification</em>.
-         *
-         * @param htmlTree the content tree to which the modifier information will be added
-         */
-        private void appendModifiers(Content htmlTree) {
-            Set<Modifier> set = new TreeSet<>(element.getModifiers());
-
-            // remove the ones we really don't need
-            set.remove(NATIVE);
-            set.remove(SYNCHRONIZED);
-            set.remove(STRICTFP);
-
-            // According to JLS, we should not be showing public modifier for
-            // interface methods and fields.
-            if ((utils.isField(element) || utils.isMethod(element))) {
-               Element te = element.getEnclosingElement();
-               if (utils.isInterface(te) || utils.isAnnotationType(te)) {
-                   // Remove the implicit abstract and public modifiers
-                   if (utils.isMethod(element)) {
-                       set.remove(ABSTRACT);
-                   }
-                   set.remove(PUBLIC);
-               }
-            }
-            if (!set.isEmpty()) {
-                String mods = set.stream().map(Modifier::toString).collect(Collectors.joining(" "));
-                htmlTree.add(HtmlTree.SPAN(HtmlStyle.modifiers, new StringContent(mods)))
-                        .add(Entity.NO_BREAK_SPACE);
-            }
-        }
-
-        /**
-         * Appends the type parameter information to the HTML tree.
-         *
-         * @param htmlTree          the HTML tree
-         * @param lastLineSeparator index of last line separator in the HTML tree
-         *
-         * @return the new index of the last line separator
-         */
-        private int appendTypeParameters(Content htmlTree, int lastLineSeparator) {
-            // Apply different wrapping strategies for type parameters
-            // depending of combined length of type parameters and return type.
-            int typeParamLength = typeParameters.charCount();
-
-            if (typeParamLength >= TYPE_PARAMS_MAX_INLINE_LENGTH) {
-                htmlTree.add(HtmlTree.SPAN(HtmlStyle.typeParametersLong, typeParameters));
-            } else {
-                htmlTree.add(HtmlTree.SPAN(HtmlStyle.typeParameters, typeParameters));
-            }
-
-            int lineLength = htmlTree.charCount() - lastLineSeparator;
-            int newLastLineSeparator = lastLineSeparator;
-
-            // sum below includes length of modifiers plus type params added above
-            if (lineLength + returnType.charCount()> RETURN_TYPE_MAX_LINE_LENGTH) {
-                htmlTree.add(DocletConstants.NL);
-                newLastLineSeparator = htmlTree.charCount();
-            } else {
-                htmlTree.add(Entity.NO_BREAK_SPACE);
-            }
-
-            return newLastLineSeparator;
-        }
-
-        /**
-         * Appends the parameters and exceptions information to the HTML tree.
-         *
-         * @param htmlTree          the HTML tree
-         * @param lastLineSeparator the index of the last line separator in the HTML tree
-         */
-        private void appendParametersAndExceptions(Content htmlTree, int lastLineSeparator) {
-            // Record current position for indentation of exceptions
-            int indentSize = htmlTree.charCount() - lastLineSeparator;
-
-            if (parameters.charCount() == 2) {
-                // empty parameters are added without packing
-                htmlTree.add(parameters);
-            } else {
-                htmlTree.add(Entity.ZERO_WIDTH_SPACE)
-                        .add(HtmlTree.SPAN(HtmlStyle.parameters, parameters));
-            }
-
-            // Exceptions
-            if (exceptions != null && !exceptions.isEmpty()) {
-                CharSequence indent = " ".repeat(Math.max(0, indentSize + 1 - 7));
-                htmlTree.add(DocletConstants.NL)
-                        .add(indent)
-                        .add("throws ")
-                        .add(HtmlTree.SPAN(HtmlStyle.exceptions, exceptions));
-            }
-        }
-    }
 }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java

@@ -114,8 +114,9 @@ public Content getAnnotationDocTreeHeader(Element member) {
 
     @Override
     public Content getSignature(Element member) {
-        return new MemberSignature(member)
-                .addType(getType(member))
+        return new Signatures.MemberSignature(member, this)
+                .setType(getType(member))
+                .setAnnotations(writer.getAnnotationInfo(member, true))
                 .toContent();
     }