stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8238506: fix obsolete comments and inconsistent exceptions in BaseTaglet

Browse Source 
Reviewed-by: prappo
This commit is contained in:
Jonathan Gibbons 2020-02-07 16:43:09 -08:00
parent c33107053b
commit faa88c1da6
5 changed files with 59 additions and 62 deletions
src/jdk.javadoc/share/classes/jdk/javadoc/internal
doclets/toolkit/taglets
BasePropertyTaglet.javaBaseTaglet.javaTaglet.javaThrowsTaglet.java
tool
Start.java

16
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BasePropertyTaglet.java

@ -49,23 +49,13 @@ public abstract class BasePropertyTaglet extends BaseTaglet {
}
/**
* This method returns the text to be put in the resulting javadoc before
* the property name.
* Returns the text to be included in the documentation before the property name.
*
* @param tagletWriter the taglet writer for output
* @return the string to be put in the resulting javadoc.
* @param tagletWriter the taglet-writer used by the doclet
* @return the text to be included in the documentation before the property name
*/
abstract String getText(TagletWriter tagletWriter);
/**
* Given the <code>Tag</code> representation of this custom
* tag, return its string representation, which is output
* to the generated page.
* @param element
* @param tag the <code>Tag</code> representation of this custom tag.
* @param tagletWriter the taglet writer for output.
* @return the TagletOutput representation of this <code>Tag</code>.
*/
@Override
public Content getTagletOutput(Element element, DocTree tag, TagletWriter tagletWriter) {
return tagletWriter.propertyTagOutput(element, tag, getText(tagletWriter));

10
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseTaglet.java

@ -188,11 +188,21 @@ public class BaseTaglet implements Taglet {
: tree.getKind() == tagKind;
}
/**
* {@inheritDoc}
*
* @implSpec This implementation throws {@link UnsupportedTagletOperationException}.
*/
@Override
public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
throw new UnsupportedTagletOperationException("Method not supported in taglet " + getName() + ".");
}
/**
* {@inheritDoc}
*
* @implSpec This implementation throws {@link UnsupportedTagletOperationException}
*/
@Override
public Content getTagletOutput(Element holder, TagletWriter writer) {
throw new UnsupportedTagletOperationException("Method not supported in taglet " + getName() + ".");

39
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/Taglet.java

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2020, 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
@ -135,29 +135,28 @@ public interface Taglet {
String getName();
/**
* Given the <code>Tag</code> representation of this custom
* tag, return its Content representation, which is output
* to the generated page.
* @param holder the element holding the tag
* @param tag the <code>Tag</code> representation of this custom tag.
* @param writer a {@link TagletWriter} Taglet writer.
* @throws UnsupportedOperationException thrown when the method is not supported by the taglet.
* @return the Content representation of this <code>Tag</code>.
* Returns the content to be included in the generated output for an
* instance of a tag handled by this taglet.
*
* @param element the element for the enclosing doc comment
* @param tag the tag
* @param writer the taglet-writer used in this doclet
* @return the output for this tag
* @throws UnsupportedTagletOperationException thrown when the method is not supported by the taglet
*/
Content getTagletOutput(Element holder, DocTree tag, TagletWriter writer) throws
UnsupportedOperationException;
Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) throws
UnsupportedTagletOperationException;
/**
* Given an element object, check if it holds any tags of
* this type. If it does, return the content representing the output.
* If it does not, return null.
* @param holder an element holding the custom tag.
* @param writer a {@link TagletWriter} Taglet writer.
* @throws UnsupportedTagletOperationException thrown when the method is not
* supported by the taglet.
* @return the content representation of this <code>Tag</code>.
* Returns the content to be included in the generated output for all
* instances of tags handled by this taglet.
*
* @param element the element for the enclosing doc comment
* @param writer the taglet-writer used in this doclet
* @return the output for this tag
* @throws UnsupportedTagletOperationException thrown when the method is not supported by the taglet
*/
Content getTagletOutput(Element holder, TagletWriter writer) throws
Content getTagletOutput(Element element, TagletWriter writer) throws
UnsupportedTagletOperationException;
class UnsupportedTagletOperationException extends UnsupportedOperationException {

42
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java

@ -77,21 +77,20 @@ public class ThrowsTaglet extends BaseTaglet
? ch.getExceptionName(input.docTreeInfo.docTree).getSignature()
: utils.getFullyQualifiedName(exception);
} else {
TypeElement element = input.utils.findClass(input.element, input.tagId);
exception = (element == null) ? null : element;
exception = input.utils.findClass(input.element, input.tagId);
}
for (DocTree dt : input.utils.getThrowsTrees(input.element)) {
Element texception = ch.getException(utils.configuration, dt);
if (texception != null && (input.tagId.equals(utils.getSimpleName(texception)) ||
(input.tagId.equals(utils.getFullyQualifiedName(texception))))) {
Element exc = ch.getException(utils.configuration, dt);
if (exc != null && (input.tagId.equals(utils.getSimpleName(exc)) ||
(input.tagId.equals(utils.getFullyQualifiedName(exc))))) {
output.holder = input.element;
output.holderTag = dt;
output.inlineTags = ch.getBody(input.utils.configuration, output.holderTag);
output.tagList.add(dt);
} else if (exception != null && texception != null &&
utils.isTypeElement(texception) && utils.isTypeElement(exception) &&
utils.isSubclassOf((TypeElement)texception, (TypeElement)exception)) {
} else if (exception != null && exc != null &&
utils.isTypeElement(exc) && utils.isTypeElement(exception) &&
utils.isSubclassOf((TypeElement)exc, (TypeElement)exception)) {
output.tagList.add(dt);
}
}
@ -106,15 +105,15 @@ public class ThrowsTaglet extends BaseTaglet
Content result = writer.getOutputInstance();
//Add links to the exceptions declared but not documented.
for (TypeMirror declaredExceptionType : declaredExceptionTypes) {
TypeElement klass = utils.asTypeElement(declaredExceptionType);
if (klass != null &&
TypeElement te = utils.asTypeElement(declaredExceptionType);
if (te != null &&
!alreadyDocumented.contains(declaredExceptionType.toString()) &&
!alreadyDocumented.contains(utils.getFullyQualifiedName(klass, false))) {
!alreadyDocumented.contains(utils.getFullyQualifiedName(te, false))) {
if (alreadyDocumented.isEmpty()) {
result.add(writer.getThrowsHeader());
}
result.add(writer.throwsTagOutput(declaredExceptionType));
alreadyDocumented.add(utils.getSimpleName(klass));
alreadyDocumented.add(utils.getSimpleName(te));
}
}
return result;
@ -176,18 +175,17 @@ public class ThrowsTaglet extends BaseTaglet
}
/**
* Given an array of <code>Tag</code>s representing this custom
* tag, return its string representation.
* @param throwTags the array of <code>ThrowsTag</code>s to convert.
* @param writer the TagletWriter that will write this tag.
* @param alreadyDocumented the set of exceptions that have already
* been documented.
* @param allowDups True if we allow duplicate throws tags to be documented.
* @return the Content representation of this <code>Tag</code>.
* Returns the generated content for a collection of {@code @throws} tags.
*
* @param throwTags the collection of tags to be converted
* @param writer the taglet-writer used by the doclet
* @param alreadyDocumented the set of exceptions that have already been documented
* @param allowDuplicates {@code true} if we allow duplicate tags to be documented
* @return the generated content for the tags
*/
protected Content throwsTagsOutput(Map<List<? extends DocTree>, ExecutableElement> throwTags,
TagletWriter writer, Set<String> alreadyDocumented,
Map<String,TypeMirror> typeSubstitutions, boolean allowDups) {
Map<String,TypeMirror> typeSubstitutions, boolean allowDuplicates) {
Utils utils = writer.configuration().utils;
Content result = writer.getOutputInstance();
if (!throwTags.isEmpty()) {
@ -198,7 +196,7 @@ public class ThrowsTaglet extends BaseTaglet
Element te = ch.getException(utils.configuration, dt);
String excName = ch.getExceptionName(dt).toString();
TypeMirror substituteType = typeSubstitutions.get(excName);
if ((!allowDups) &&
if ((!allowDuplicates) &&
(alreadyDocumented.contains(excName) ||
(te != null && alreadyDocumented.contains(utils.getFullyQualifiedName(te, false)))) ||
(substituteType != null && alreadyDocumented.contains(substituteType.toString()))) {

14
src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java

@ -399,14 +399,14 @@ public class Start {
Throwable t = e.getCause();
dumpStack(t == null ? e : t);
return ERROR;
} catch (OptionException toe) {
if (toe.message != null)
messager.printError(toe.message);
} catch (OptionException oe) {
if (oe.message != null)
messager.printError(oe.message);
toe.m.run();
Throwable t = toe.getCause();
dumpStack(t == null ? toe : t);
return toe.result;
oe.m.run();
Throwable t = oe.getCause();
dumpStack(t == null ? oe : t);
return oe.result;
} catch (ToolException exc) {
if (exc.message != null) {
messager.printError(exc.message);