archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 15:24:43 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8224052: Javadoc doesn't handle non-public intermediate types well

Browse source 
Reviewed-by: jjg
This commit is contained in:
Hannes Wallnöfer 2020-01-16 15:50:23 +01:00
parent 995fae6d4b
commit 5903e20af2
17 changed files with 244 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -35,6 +35,7 @@ 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.SimpleTypeVisitor9;
@ -141,10 +142,10 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
* @param isVarArg true if this is a link to var arg.
* @param tree the content tree to which the parameter information will be added.
*/
protected void addParam(ExecutableElement member, VariableElement param,
protected void addParam(ExecutableElement member, VariableElement param, TypeMirror paramType,
boolean isVarArg, Content tree) {
Content link = writer.getLink(new LinkInfoImpl(configuration, EXECUTABLE_MEMBER_PARAM,
param.asType()).varargs(isVarArg));
paramType).varargs(isVarArg));
tree.add(link);
if(name(param).length() > 0) {
tree.add(Entity.NO_BREAK_SPACE);
@ -208,9 +209,11 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
sep = "," + DocletConstants.NL;
}
int paramstart;
ExecutableType instMeth = utils.asInstantiatedMethodType(typeElement, member);
for (paramstart = 0; paramstart < parameters.size(); paramstart++) {
paramTree.add(sep);
VariableElement param = parameters.get(paramstart);
TypeMirror paramType = instMeth.getParameterTypes().get(paramstart);
if (param.getKind() != ElementKind.INSTANCE_INIT) {
if (includeAnnotations) {
@ -220,7 +223,7 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
paramTree.add(DocletConstants.NL);
}
}
addParam(member, param,
addParam(member, param, paramType,
(paramstart == parameters.size() - 1) && member.isVarArgs(), paramTree);
break;
}
@ -237,7 +240,8 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
paramTree.add(DocletConstants.NL);
}
}
addParam(member, parameters.get(i), (i == parameters.size() - 1) && member.isVarArgs(),
addParam(member, parameters.get(i), instMeth.getParameterTypes().get(i),
(i == parameters.size() - 1) && member.isVarArgs(),
paramTree);
}
@ -251,7 +255,7 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
* @return the content tree containing the exceptions information.
*/
protected Content getExceptions(ExecutableElement member) {
List<? extends TypeMirror> exceptions = member.getThrownTypes();
List<? extends TypeMirror> exceptions = utils.asInstantiatedMethodType(typeElement, member).getThrownTypes();
Content htmltree = new ContentBuilder();
if (!exceptions.isEmpty()) {
Content link = writer.getLink(new LinkInfoImpl(configuration, MEMBER, exceptions.get(0)));

2
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeFieldWriterImpl.java
View file

@ -264,7 +264,7 @@ public class AnnotationTypeFieldWriterImpl extends AbstractMemberWriter
if (utils.isConstructor(member))
return null;
if (utils.isExecutableElement(member))
return utils.getReturnType((ExecutableElement)member);
return utils.getReturnType(typeElement, (ExecutableElement)member);
return member.asType();
}
}

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

@ -266,7 +266,7 @@ public class AnnotationTypeRequiredMemberWriterImpl extends AbstractMemberWriter
private TypeMirror getType(Element member) {
return utils.isExecutableElement(member)
? utils.getReturnType((ExecutableElement) member)
? utils.getReturnType(typeElement, (ExecutableElement) member)
: member.asType();
}
}

8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java
View file

@ -204,6 +204,14 @@ public class ClassWriterImpl extends SubWriterHolderWriter implements ClassWrite
return getMemberTree(HtmlStyle.description, classInfoTree);
}
/**
* {@inheritDoc}
*/
@Override
protected TypeElement getCurrentPageElement() {
return typeElement;
}
/**
* {@inheritDoc}
*/

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FieldWriterImpl.java
View file

@ -115,7 +115,7 @@ public class FieldWriterImpl extends AbstractMemberWriter
@Override
public Content getSignature(VariableElement field) {
return new MemberSignature(field)
.addType(field.asType())
.addType(utils.asInstantiatedFieldType(typeElement, field))
.toContent();
}
@ -262,7 +262,7 @@ public class FieldWriterImpl extends AbstractMemberWriter
*/
@Override
protected void addSummaryType(Element member, Content tdSummaryType) {
addModifierAndType(member, member.asType(), tdSummaryType);
addModifierAndType(member, utils.asInstantiatedFieldType(typeElement, (VariableElement)member), tdSummaryType);
}
/**

9
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
View file

@ -860,6 +860,15 @@ public class HtmlDocletWriter {
return (encl.isUnnamed()) ? "" : (encl.getQualifiedName() + ".");
}
/**
* Return the main type element of the current page or null for pages that don't have one.
*
* @return the type element of the current page.
*/
protected TypeElement getCurrentPageElement() {
return null;
}
/**
* Add the class link, with only class name as the strong link and prefixing
* plain package name.

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriterImpl.java
View file

@ -290,7 +290,7 @@ public class MethodWriterImpl extends AbstractExecutableMemberWriter
@Override
protected void addSummaryType(Element member, Content tdSummaryType) {
ExecutableElement meth = (ExecutableElement)member;
addModifierAndType(meth, utils.getReturnType(meth), tdSummaryType);
addModifierAndType(meth, utils.getReturnType(typeElement, meth), tdSummaryType);
}
/**
@ -386,7 +386,7 @@ public class MethodWriterImpl extends AbstractExecutableMemberWriter
* @return content containing the return type
*/
protected Content getReturnType(ExecutableElement method) {
TypeMirror type = utils.getReturnType(method);
TypeMirror type = utils.getReturnType(typeElement, method);
if (type != null) {
return writer.getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.RETURN_TYPE, type));
}

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PropertyWriterImpl.java
View file

@ -109,7 +109,7 @@ public class PropertyWriterImpl extends AbstractMemberWriter
@Override
public Content getSignature(ExecutableElement property) {
return new MemberSignature(property)
.addType(utils.getReturnType(property))
.addType(utils.getReturnType(typeElement, property))
.toContent();
}
@ -282,7 +282,7 @@ public class PropertyWriterImpl extends AbstractMemberWriter
*/
@Override
protected void addSummaryType(Element member, Content tdSummaryType) {
addModifierAndType(member, utils.getReturnType((ExecutableElement)member), tdSummaryType);
addModifierAndType(member, utils.getReturnType(typeElement, (ExecutableElement)member), tdSummaryType);
}
/**

14
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java
View file

@ -341,12 +341,15 @@ public class TagletWriterImpl extends TagletWriter {
/**
* {@inheritDoc}
*/
public Content throwsTagOutput(Element element, DocTree throwsTag) {
public Content throwsTagOutput(Element element, DocTree throwsTag, TypeMirror substituteType) {
ContentBuilder body = new ContentBuilder();
CommentHelper ch = utils.getCommentHelper(element);
Element exception = ch.getException(configuration, throwsTag);
Content excName;
if (exception == null) {
if (substituteType != null) {
excName = htmlWriter.getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.MEMBER,
substituteType));
} else if (exception == null) {
excName = new RawHtml(ch.getExceptionName(throwsTag).toString());
} else if (exception.asType() == null) {
excName = new RawHtml(utils.getFullyQualifiedName(exception));
@ -415,6 +418,13 @@ public class TagletWriterImpl extends TagletWriter {
return configuration;
}
/**
* {@inheritDoc}
*/
protected TypeElement getCurrentPageElement() {
return htmlWriter.getCurrentPageElement();
}
@SuppressWarnings("preview")
private Content createAnchorAndSearchIndex(Element element, String tagText, String desc, boolean isSystemProperty) {
Content result = null;

2
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java
View file

@ -74,7 +74,7 @@ public class ReturnTaglet extends BaseTaglet implements InheritableTaglet {
public Content getTagletOutput(Element holder, TagletWriter writer) {
Messages messages = writer.configuration().getMessages();
Utils utils = writer.configuration().utils;
TypeMirror returnType = utils.getReturnType((ExecutableElement)holder);
TypeMirror returnType = utils.getReturnType(writer.getCurrentPageElement(), (ExecutableElement)holder);
List<? extends DocTree> tags = utils.getBlockTags(holder, name);
//Make sure we are not using @return tag on method with void return type.

11
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletWriter.java
View file

@ -27,6 +27,7 @@ package jdk.javadoc.internal.doclets.toolkit.taglets;
import java.util.List;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.lang.model.type.TypeMirror;
@ -189,9 +190,10 @@ public abstract class TagletWriter {
*
* @param element
* @param throwsTag the throws tag.
* @param substituteType instantiated type of a generic type-variable, or null.
* @return the output of the throws tag.
*/
protected abstract Content throwsTagOutput(Element element, DocTree throwsTag);
protected abstract Content throwsTagOutput(Element element, DocTree throwsTag, TypeMirror substituteType);
/**
* Return the output for the throws tag.
@ -213,6 +215,13 @@ public abstract class TagletWriter {
protected abstract Content valueTagOutput(VariableElement field,
String constantVal, boolean includeLink);
/**
* Return the main type element of the current page or null for pages that don't have one.
*
* @return the type element of the current page or null.
*/
protected abstract TypeElement getCurrentPageElement();
/**
* Given an output object, append to it the tag documentation for
* the given member.

66
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java
View file

@ -31,6 +31,7 @@ import java.util.Map.Entry;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.type.ExecutableType;
import javax.lang.model.type.TypeMirror;
import com.sun.source.doctree.DocTree;
@ -99,8 +100,8 @@ public class ThrowsTaglet extends BaseTaglet
for (TypeMirror declaredExceptionType : declaredExceptionTypes) {
TypeElement klass = utils.asTypeElement(declaredExceptionType);
if (klass != null &&
!alreadyDocumented.contains(utils.getSimpleName(klass)) &&
!alreadyDocumented.contains(utils.getFullyQualifiedName(klass))) {
!alreadyDocumented.contains(declaredExceptionType.toString()) &&
!alreadyDocumented.contains(utils.getFullyQualifiedName(klass, false))) {
if (alreadyDocumented.isEmpty()) {
result.add(writer.getThrowsHeader());
}
@ -117,7 +118,7 @@ public class ThrowsTaglet extends BaseTaglet
*/
private Content inheritThrowsDocumentation(Element holder,
List<? extends TypeMirror> declaredExceptionTypes, Set<String> alreadyDocumented,
TagletWriter writer) {
Map<String, TypeMirror> typeSubstitutions, TagletWriter writer) {
Utils utils = writer.configuration().utils;
Content result = writer.getOutputInstance();
if (utils.isExecutableElement(holder)) {
@ -138,7 +139,8 @@ public class ThrowsTaglet extends BaseTaglet
declaredExceptionTags.put(inheritedDoc.tagList, (ExecutableElement)inheritedDoc.holder);
}
}
result.add(throwsTagsOutput(declaredExceptionTags, writer, alreadyDocumented, false));
result.add(throwsTagsOutput(declaredExceptionTags, writer, alreadyDocumented,
typeSubstitutions, false));
}
return result;
}
@ -149,17 +151,21 @@ public class ThrowsTaglet extends BaseTaglet
public Content getTagletOutput(Element holder, TagletWriter writer) {
Utils utils = writer.configuration().utils;
ExecutableElement execHolder = (ExecutableElement) holder;
ExecutableType instantiatedType = utils.asInstantiatedMethodType(
writer.getCurrentPageElement(), (ExecutableElement)holder);
List<? extends TypeMirror> thrownTypes = instantiatedType.getThrownTypes();
Map<String, TypeMirror> typeSubstitutions = getSubstitutedThrownTypes(
((ExecutableElement) holder).getThrownTypes(), thrownTypes);
Map<List<? extends DocTree>, ExecutableElement> tagsMap = new LinkedHashMap<>();
tagsMap.put(utils.getThrowsTrees(execHolder), execHolder);
Content result = writer.getOutputInstance();
HashSet<String> alreadyDocumented = new HashSet<>();
if (!tagsMap.isEmpty()) {
result.add(throwsTagsOutput(tagsMap, writer, alreadyDocumented, true));
result.add(throwsTagsOutput(tagsMap, writer, alreadyDocumented, typeSubstitutions, true));
}
result.add(inheritThrowsDocumentation(holder,
execHolder.getThrownTypes(), alreadyDocumented, writer));
result.add(linkToUndocumentedDeclaredExceptions(
execHolder.getThrownTypes(), alreadyDocumented, writer));
thrownTypes, alreadyDocumented, typeSubstitutions, writer));
result.add(linkToUndocumentedDeclaredExceptions(thrownTypes, alreadyDocumented, writer));
return result;
}
@ -174,7 +180,8 @@ public class ThrowsTaglet extends BaseTaglet
* @return the Content representation of this <code>Tag</code>.
*/
protected Content throwsTagsOutput(Map<List<? extends DocTree>, ExecutableElement> throwTags,
TagletWriter writer, Set<String> alreadyDocumented, boolean allowDups) {
TagletWriter writer, Set<String> alreadyDocumented,
Map<String,TypeMirror> typeSubstitutions, boolean allowDups) {
Utils utils = writer.configuration().utils;
Content result = writer.getOutputInstance();
if (!throwTags.isEmpty()) {
@ -184,21 +191,52 @@ public class ThrowsTaglet extends BaseTaglet
for (DocTree dt : entry.getKey()) {
Element te = ch.getException(utils.configuration, dt);
String excName = ch.getExceptionName(dt).toString();
TypeMirror substituteType = typeSubstitutions.get(excName);
if ((!allowDups) &&
(alreadyDocumented.contains(excName) ||
(te != null && alreadyDocumented.contains(utils.getFullyQualifiedName(te))))) {
(te != null && alreadyDocumented.contains(utils.getFullyQualifiedName(te, false)))) ||
(substituteType != null && alreadyDocumented.contains(substituteType.toString()))) {
continue;
}
if (alreadyDocumented.isEmpty()) {
result.add(writer.getThrowsHeader());
}
result.add(writer.throwsTagOutput(e, dt));
alreadyDocumented.add(te != null
? utils.getFullyQualifiedName(te)
: excName);
result.add(writer.throwsTagOutput(e, dt, substituteType));
if (substituteType != null) {
alreadyDocumented.add(substituteType.toString());
} else {
alreadyDocumented.add(te != null
? utils.getFullyQualifiedName(te, false)
: excName);
}
}
}
}
return result;
}
/**
* Returns a map of substitutions for a list of thrown types with the original type-variable
* name as key and the instantiated type as value. If no types need to be substituted
* an empty map is returned.
* @param declaredThrownTypes the originally declared thrown types.
* @param instantiatedThrownTypes the thrown types in the context of the current type.
* @return map of declared to instantiated thrown types or an empty map.
*/
private Map<String, TypeMirror> getSubstitutedThrownTypes(List<? extends TypeMirror> declaredThrownTypes,
List<? extends TypeMirror> instantiatedThrownTypes) {
if (!instantiatedThrownTypes.equals(declaredThrownTypes)) {
Map<String, TypeMirror> map = new HashMap<>();
Iterator<? extends TypeMirror> i1 = instantiatedThrownTypes.iterator();
Iterator<? extends TypeMirror> i2 = declaredThrownTypes.iterator();
while (i1.hasNext() && i2.hasNext()) {
TypeMirror t1 = i1.next();
TypeMirror t2 = i2.next();
if (!t1.equals(t2))
map.put(t2.toString(), t1);
}
return map;
}
return Collections.emptyMap();
}
}

53
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
View file

@ -219,7 +219,7 @@ public class Utils {
* @return true if t1 is a superclass of t2.
*/
public boolean isSubclassOf(TypeElement t1, TypeElement t2) {
return typeUtils.isSubtype(t1.asType(), t2.asType());
return typeUtils.isSubtype(typeUtils.erasure(t1.asType()), typeUtils.erasure(t2.asType()));
}
/**
@ -565,7 +565,8 @@ public class Utils {
}
public boolean isUndocumentedEnclosure(TypeElement enclosingTypeElement) {
return isPackagePrivate(enclosingTypeElement) && !isLinkable(enclosingTypeElement);
return (isPackagePrivate(enclosingTypeElement) || isPrivate(enclosingTypeElement))
&& !isLinkable(enclosingTypeElement);
}
public boolean isError(TypeElement te) {
@ -796,13 +797,51 @@ public class Utils {
}
/**
* Returns the TypeMirror of the ExecutableElement for all methods,
* a null if constructor.
* Returns the TypeMirror of the ExecutableElement if it is a method, or null
* if it is a constructor.
* @param site the contextual type
* @param ee the ExecutableElement
* @return
* @return the return type
*/
public TypeMirror getReturnType(ExecutableElement ee) {
return ee.getKind() == CONSTRUCTOR ? null : ee.getReturnType();
public TypeMirror getReturnType(TypeElement site, ExecutableElement ee) {
return ee.getKind() == CONSTRUCTOR ? null : asInstantiatedMethodType(site, ee).getReturnType();
}
/**
* Returns the ExecutableType corresponding to the type of the method declaration seen as a
* member of a given declared type. This might cause type-variable substitution to kick in.
* @param site the contextual type.
* @param ee the method declaration.
* @return the instantiated method type.
*/
public ExecutableType asInstantiatedMethodType(TypeElement site, ExecutableElement ee) {
return shouldInstantiate(site, ee) ?
(ExecutableType)typeUtils.asMemberOf((DeclaredType)site.asType(), ee) :
(ExecutableType)ee.asType();
}
/**
* Returns the TypeMirror corresponding to the type of the field declaration seen as a
* member of a given declared type. This might cause type-variable substitution to kick in.
* @param site the contextual type.
* @param ve the field declaration.
* @return the instantiated field type.
*/
public TypeMirror asInstantiatedFieldType(TypeElement site, VariableElement ve) {
return shouldInstantiate(site, ve) ?
typeUtils.asMemberOf((DeclaredType)site.asType(), ve) :
ve.asType();
}
/*
* We should not instantiate if (i) there's no contextual type declaration, (ii) the declaration
* to which the member belongs to is the same as the one under consideration, (iii) if the
* delcaration to which the member belongs to is not generic.
*/
private boolean shouldInstantiate(TypeElement site, Element e) {
return site != null &&
site != e.getEnclosingElement() &&
!((DeclaredType)e.getEnclosingElement().asType()).getTypeArguments().isEmpty();
}
/**