Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files
8245058: improve presentation of annotations for modules and packages
Reviewed-by: jjg
  • Loading branch information
hns committed Nov 27, 2020
1 parent d51e2ab commit 5be4de8583ac3f95226e030c564dd47c3e7c8a7c
Showing with 1,094 additions and 930 deletions.
  1. +11 −12 ...vadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java
  2. +0 −231 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java
  3. +3 −2 ...are/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java
  4. +4 −102 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java
  5. +4 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriterImpl.java
  6. +3 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/EnumConstantWriterImpl.java
  7. +3 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FieldWriterImpl.java
  8. +13 −59 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
  9. +5 −13 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/LinkFactoryImpl.java
  10. +6 −5 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriterImpl.java
  11. +6 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java
  12. +6 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java
  13. +3 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PropertyWriterImpl.java
  14. +441 −0 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java
  15. +38 −12 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java
  16. +8 −0 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ModuleSummaryWriter.java
  17. +8 −0 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/PackageSummaryWriter.java
  18. +1 −0 ...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java
  19. +1 −0 ...dk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PackageSummaryBuilder.java
  20. +12 −10 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
  21. +4 −5 test/langtools/jdk/javadoc/doclet/testAnnotationTypes/TestAnnotationTypes.java
  22. +30 −28 test/langtools/jdk/javadoc/doclet/testDeprecatedDocs/TestDeprecatedDocs.java
  23. +3 −2 test/langtools/jdk/javadoc/doclet/testHiddenTag/TestHiddenTag.java
  24. +2 −1 test/langtools/jdk/javadoc/doclet/testHref/TestHref.java
  25. +7 −8 test/langtools/jdk/javadoc/doclet/testHtmlDefinitionListTag/TestHtmlDefinitionListTag.java
  26. +8 −6 test/langtools/jdk/javadoc/doclet/testHtmlTag/TestHtmlTag.java
  27. +1 −2 test/langtools/jdk/javadoc/doclet/testIndentation/TestIndentation.java
  28. +8 −9 test/langtools/jdk/javadoc/doclet/testInterface/TestInterface.java
  29. +20 −22 test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFX.java
  30. +2 −2 test/langtools/jdk/javadoc/doclet/testLambdaFeature/TestLambdaFeature.java
  31. +11 −7 test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java
  32. +2 −2 test/langtools/jdk/javadoc/doclet/testLiteralCodeInPre/TestLiteralCodeInPre.java
  33. +11 −10 test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java
  34. +1 −1 test/langtools/jdk/javadoc/doclet/testMemberSummary/TestMemberSummary.java
  35. +10 −10 test/langtools/jdk/javadoc/doclet/testMethodSignature/TestMethodSignature.java
  36. +10 −5 test/langtools/jdk/javadoc/doclet/testModifierEx/TestModifierEx.java
  37. +30 −37 test/langtools/jdk/javadoc/doclet/testModules/TestModules.java
  38. +38 −33 test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java
  39. +27 −22 test/langtools/jdk/javadoc/doclet/testOptions/TestOptions.java
  40. +4 −8 test/langtools/jdk/javadoc/doclet/testOrdering/TestOrdering.java
  41. +1 −2 test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestBadOverride.java
  42. +2 −2 test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverriddenDeprecatedMethods.java
  43. +7 −5 test/langtools/jdk/javadoc/doclet/testPackageAnnotation/TestPackageAnnotation.java
  44. +8 −5 test/langtools/jdk/javadoc/doclet/testPrivateClasses/TestPrivateClasses.java
  45. +4 −4 test/langtools/jdk/javadoc/doclet/testProperty/TestProperty.java
  46. +19 −18 test/langtools/jdk/javadoc/doclet/testRecordTypes/TestRecordTypes.java
  47. +77 −42 test/langtools/jdk/javadoc/doclet/testSealedTypes/TestSealedTypes.java
  48. +1 −1 ...langtools/jdk/javadoc/doclet/testSerializedFormWithClassFile/TestSerializedFormWithClassFile.java
  49. +1 −1 test/langtools/jdk/javadoc/doclet/testStylesheet/TestStylesheet.java
  50. +1 −1 test/langtools/jdk/javadoc/doclet/testSummaryTag/TestSummaryTag.java
  51. +1 −1 test/langtools/jdk/javadoc/doclet/testThrows/TestThrows.java
  52. +162 −162 test/langtools/jdk/javadoc/doclet/testTypeAnnotations/TestTypeAnnotations.java
  53. +5 −5 test/langtools/jdk/javadoc/doclet/testTypeParams/TestTypeParameters.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),
@@ -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));
}
}
}
}
@@ -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();
}

0 comments on commit 5be4de8

Please sign in to comment.