Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

JDK-8261263: Simplify javadoc link code #2437

Closed
wants to merge 2 commits into from
Closed

JDK-8261263: Simplify javadoc link code #2437

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
129735e
JDK-8261263: Simplify javadoc link code
hns Feb 5, 2021
fb7f07d
JDK-8261263: Reformat and rephrase comments
hns Feb 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
9 changes: 4 additions & 5 deletions ...are/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java
View file
Open in desktop
Expand Up @@ -32,11 +32,9 @@
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.lang.model.type.ArrayType;
import javax.lang.model.type.DeclaredType;
import javax.lang.model.type.ExecutableType;
import javax.lang.model.type.TypeMirror;
import javax.lang.model.type.TypeVariable;
import javax.lang.model.util.SimpleTypeVisitor14;

import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
Expand Down Expand Up @@ -97,7 +95,8 @@ protected Content getSummaryLink(Element member) {
}
content.add(signature);

return writer.getDocLink(MEMBER_DEPRECATED_PREVIEW, utils.getEnclosingTypeElement(member), member, content);
return writer.getDocLink(MEMBER_DEPRECATED_PREVIEW, utils.getEnclosingTypeElement(member),
member, content, false);
}

/**
Expand All @@ -113,7 +112,7 @@ protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement te, Element
Content tdSummary) {
ExecutableElement ee = (ExecutableElement)member;
Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
writer.getDocLink(context, te, ee, name(ee), false));
writer.getDocLink(context, te, ee, name(ee)));
Content code = HtmlTree.CODE(memberLink);
addParameters(ee, code);
tdSummary.add(code);
Expand All @@ -128,7 +127,7 @@ protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement te, Element
*/
@Override
protected void addInheritedSummaryLink(TypeElement te, Element member, Content linksTree) {
linksTree.add(writer.getDocLink(MEMBER, te, member, name(member), false));
linksTree.add(writer.getDocLink(MEMBER, te, member, name(member)));
}

/**
Expand Down
2 changes: 1 addition & 1 deletion ...ses/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java
View file
Open in desktop
Expand Up @@ -187,7 +187,7 @@ public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedT
protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member,
Content tdSummary) {
Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
writer.getDocLink(context, member, name(member), false));
writer.getDocLink(context, member, name(member)));
Content code = HtmlTree.CODE(memberLink);
tdSummary.add(code);
}
Expand Down
4 changes: 2 additions & 2 deletions ...c/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstantsSummaryWriterImpl.java
View file
Open in desktop
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -237,7 +237,7 @@ private Content getTypeColumn(VariableElement member) {
*/
private Content getNameColumn(VariableElement member) {
Content nameContent = getDocLink(LinkInfoImpl.Kind.CONSTANT_SUMMARY,
member, member.getSimpleName(), false);
member, member.getSimpleName());
return HtmlTree.CODE(nameContent);
}

Expand Down
2 changes: 1 addition & 1 deletion ...vadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/EnumConstantWriterImpl.java
View file
Open in desktop
Expand Up @@ -160,7 +160,7 @@ public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedT
protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member,
Content tdSummary) {
Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
writer.getDocLink(context, member, name(member), false));
writer.getDocLink(context, member, name(member)));
Content code = HtmlTree.CODE(memberLink);
tdSummary.add(code);
}
Expand Down
7 changes: 3 additions & 4 deletions src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FieldWriterImpl.java
View file
Open in desktop
Expand Up @@ -161,7 +161,7 @@ protected Table createSummaryTable() {
@Override
public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) {
Content classLink = writer.getPreQualifiedClassLink(
LinkInfoImpl.Kind.MEMBER, typeElement, false);
LinkInfoImpl.Kind.MEMBER, typeElement);
Content label;
if (options.summarizeOverriddenMethods()) {
label = new StringContent(utils.isClass(typeElement)
Expand All @@ -184,16 +184,15 @@ public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedT
protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member,
Content tdSummary) {
Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
writer.getDocLink(context, typeElement , member, name(member), false));
writer.getDocLink(context, typeElement , member, name(member)));
Content code = HtmlTree.CODE(memberLink);
tdSummary.add(code);
}

@Override
protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree) {
linksTree.add(
writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member,
name(member), false));
writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member, name(member)));
}

@Override
Expand Down
93 changes: 23 additions & 70 deletions ...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
View file
Open in desktop
Expand Up @@ -763,7 +763,7 @@ public Content getLink(LinkInfoImpl linkInfo) {
*/
public Content getTypeParameterLinks(LinkInfoImpl linkInfo) {
LinkFactoryImpl factory = new LinkFactoryImpl(this);
return factory.getTypeParameterLinks(linkInfo, false);
return factory.getTypeParameterLinks(linkInfo);
}

/*************************************************************
Expand Down Expand Up @@ -853,18 +853,16 @@ public void addPreQualifiedClassLink(LinkInfoImpl.Kind context, TypeElement type
* link label.
*
* @param typeElement the class to link to.
* @param isStrong true if the link should be strong.
* @return the link with the package portion of the label in plain text.
*/
public Content getPreQualifiedClassLink(LinkInfoImpl.Kind context,
TypeElement typeElement, boolean isStrong) {
public Content getPreQualifiedClassLink(LinkInfoImpl.Kind context, TypeElement typeElement) {
ContentBuilder classlink = new ContentBuilder();
PackageElement pkg = utils.containingPackage(typeElement);
if (pkg != null && ! configuration.shouldExcludeQualifier(pkg.getSimpleName().toString())) {
classlink.add(getEnclosingPackageName(typeElement));
}
classlink.add(getLink(new LinkInfoImpl(configuration,
context, typeElement).label(utils.getSimpleName(typeElement)).strong(isStrong)));
context, typeElement).label(utils.getSimpleName(typeElement))));
return classlink;
}

Expand Down Expand Up @@ -934,65 +932,55 @@ public void addPreQualifiedStrongClassLink(LinkInfoImpl.Kind context, TypeElemen
*/
public Content getDocLink(LinkInfoImpl.Kind context, Element element, CharSequence label) {
return getDocLink(context, utils.getEnclosingTypeElement(element), element,
new StringContent(label));
new StringContent(label), false);
}

/**
* Return the link for the given member.
*
* @param context the id of the context where the link will be printed.
* @param typeElement the typeElement that we should link to. This is not
* not necessarily the type containing element since we may be
* inheriting comments.
* @param element the member being linked to.
* @param label the label for the link.
* @param strong true if the link should be strong.
* @return the link for the given member.
*/
public Content getDocLink(LinkInfoImpl.Kind context, Element element, CharSequence label,
boolean strong) {
return getDocLink(context, utils.getEnclosingTypeElement(element), element, label, strong);
public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
CharSequence label) {
return getDocLink(context, typeElement, element, label, false);
}

/**
* Return the link for the given member.
*
* @param context the id of the context where the link will be printed.
* @param typeElement the typeElement that we should link to. This is not
necessarily equal to element.containingClass(). We may be
inheriting comments.
* @param typeElement the typeElement that we should link to. This is not
* not necessarily the type containing element since we may be
* inheriting comments.
* @param element the member being linked to.
* @param label the label for the link.
* @param strong true if the link should be strong.
* @return the link for the given member.
*/
public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
CharSequence label, boolean strong) {
return getDocLink(context, typeElement, element, label, strong, false);
}

public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
Content label, boolean strong) {
return getDocLink(context, typeElement, element, label, strong, false);
CharSequence label, boolean isProperty) {
return getDocLink(context, typeElement, element, new StringContent(label), isProperty);
}

/**
* Return the link for the given member.
*
* @param context the id of the context where the link will be printed.
* @param typeElement the typeElement that we should link to. This is not
necessarily equal to element.containingClass(). We may be
inheriting comments.
* @param typeElement the typeElement that we should link to. This is not
* not necessarily the type containing element since we may be
* inheriting comments.
* @param element the member being linked to.
* @param label the label for the link.
* @param strong true if the link should be strong.
* @param isProperty true if the element parameter is a JavaFX property.
* @return the link for the given member.
*/
public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
CharSequence label, boolean strong, boolean isProperty) {
return getDocLink(context, typeElement, element, new StringContent(label), strong, isProperty);
}

public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
Content label, boolean strong, boolean isProperty) {
Content label, boolean isProperty) {
if (!utils.isLinkable(typeElement, element)) {
return label;
}
Expand All @@ -1003,52 +991,19 @@ public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, El
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(id.name())
.targetMember(element)
.strong(strong));
.targetMember(element));
}

if (utils.isVariableElement(element) || utils.isTypeElement(element)) {
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(element.getSimpleName().toString())
.targetMember(element)
.strong(strong));
.targetMember(element));
}

return label;
}

/**
* Return the link for the given member.
*
* @param context the id of the context where the link will be added
* @param typeElement the typeElement that we should link to. This is not
necessarily equal to element.containingClass(). We may be
inheriting comments
* @param element the member being linked to
* @param label the label for the link
* @return the link for the given member
*/
public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
Content label) {
if (!(utils.isIncluded(element) || utils.isLinkable(typeElement))) {
return label;
} else if (utils.isExecutableElement(element)) {
ExecutableElement emd = (ExecutableElement) element;
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(htmlIds.forMember(emd).name())
.targetMember(element));
} else if (utils.isVariableElement(element) || utils.isTypeElement(element)) {
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(element.getSimpleName().toString())
.targetMember(element));
} else {
return label;
}
}

public Content seeTagToContent(Element element, DocTree see) {
Kind kind = see.getKind();
if (!(kind == LINK || kind == SEE || kind == LINK_PLAIN)) {
Expand Down Expand Up @@ -1900,8 +1855,7 @@ private void addAnnotations(TypeElement annotationDoc, LinkInfoImpl linkInfo,
}
String simpleName = element.getSimpleName().toString();
if (multipleValues || !"value".equals(simpleName)) { // Omit "value=" where unnecessary
annotation.add(getDocLink(LinkInfoImpl.Kind.ANNOTATION,
element, simpleName, false));
annotation.add(getDocLink(LinkInfoImpl.Kind.ANNOTATION, element, simpleName));
annotation.add("=");
}
AnnotationValue annotationValue = map.get(element);
Expand Down Expand Up @@ -2015,8 +1969,7 @@ public Content visitAnnotation(AnnotationMirror a, Void p) {
}
@Override
public Content visitEnumConstant(VariableElement c, Void p) {
return getDocLink(LinkInfoImpl.Kind.ANNOTATION,
c, c.getSimpleName(), false);
return getDocLink(LinkInfoImpl.Kind.ANNOTATION, c, c.getSimpleName());
}
@Override
public Content visitArray(List<? extends AnnotationValue> vals, Void p) {
Expand Down
5 changes: 3 additions & 2 deletions src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexWriter.java
View file
Open in desktop
@@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -226,7 +226,8 @@ protected void addElementDescription(IndexItem item, Content dlTree) {
case ENUM_CONSTANT:
TypeElement containingType = item.getContainingTypeElement();
dt = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.memberNameLink,
getDocLink(LinkInfoImpl.Kind.INDEX, containingType, element, new StringContent(label))));
getDocLink(LinkInfoImpl.Kind.INDEX, containingType, element,
new StringContent(label), false)));
dt.add(" - ");
addMemberDesc(element, containingType, dt);
break;
Expand Down
21 changes: 2 additions & 19 deletions src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/LinkFactoryImpl.java
View file
Open in desktop
Expand Up @@ -39,7 +39,6 @@
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.Resources;
Expand Down Expand Up @@ -78,7 +77,6 @@ protected Content newContent() {
protected Content getClassLink(LinkInfo linkInfo) {
BaseConfiguration configuration = m_writer.configuration;
LinkInfoImpl classLinkInfo = (LinkInfoImpl) linkInfo;
boolean noLabel = linkInfo.label == null || linkInfo.label.isEmpty();
TypeElement typeElement = classLinkInfo.typeElement;
// Create a tool tip if we are linking to a class or interface. Don't
// create one if we are linking to a member.
Expand Down Expand Up @@ -121,9 +119,6 @@ protected Content getClassLink(LinkInfo linkInfo) {
filename.fragment(m_writer.htmlIds.forPreviewSection(target).name()),
m_writer.contents.previewMark)));
}
if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
link.add(getTypeParameterLinks(linkInfo));
}
return link;
}
}
Expand All @@ -140,9 +135,6 @@ protected Content getClassLink(LinkInfo linkInfo) {
m_writer.contents.previewMark,
false, false)));
}
if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
link.add(getTypeParameterLinks(linkInfo));
}
return link;
}
}
Expand All @@ -151,14 +143,11 @@ protected Content getClassLink(LinkInfo linkInfo) {
if (flags.contains(ElementFlag.PREVIEW)) {
link.add(HtmlTree.SUP(m_writer.contents.previewMark));
}
if (noLabel && !classLinkInfo.excludeTypeParameterLinks) {
link.add(getTypeParameterLinks(linkInfo));
}
return link;
}

@Override
protected Content getTypeParameterLinks(LinkInfo linkInfo, boolean isClassLabel) {
protected Content getTypeParameterLinks(LinkInfo linkInfo) {
Content links = newContent();
List<TypeMirror> vars = new ArrayList<>();
TypeMirror ctype = linkInfo.type != null
Expand All @@ -176,8 +165,7 @@ protected Content getTypeParameterLinks(LinkInfo linkInfo, boolean isClassLabel)
// Nothing to document.
return links;
}
if (((linkInfo.includeTypeInClassLinkLabel && isClassLabel)
|| (linkInfo.includeTypeAsSepLink && !isClassLabel)) && !vars.isEmpty()) {
if (!vars.isEmpty()) {
links.add("<");
boolean many = false;
for (TypeMirror t : vars) {
Expand Down Expand Up @@ -284,11 +272,6 @@ private String getClassToolTip(TypeElement typeElement, boolean isTypeLink) {
* @param linkInfo the information about the link.
*/
private DocPath getPath(LinkInfoImpl linkInfo) {
if (linkInfo.context == LinkInfoImpl.Kind.PACKAGE_FRAME) {
//Not really necessary to do this but we want to be consistent
//with 1.4.2 output.
return docPaths.forName(linkInfo.typeElement);
}
return m_writer.pathToRoot.resolve(docPaths.forClass(linkInfo.typeElement));
}
}