Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
8252717: Integrate/merge legacy standard doclet diagnostics and doclint
Reviewed-by: erikj, prappo
  • Loading branch information
jonathan-gibbons committed Jun 3, 2022
1 parent 28c112f commit 59e9700
Show file tree
Hide file tree
Showing 11 changed files with 246 additions and 39 deletions.
4 changes: 2 additions & 2 deletions make/Docs.gmk
Expand Up @@ -104,14 +104,14 @@ JAVADOC_DISABLED_DOCLINT_PACKAGES := org.w3c.* javax.smartcardio

# The initial set of options for javadoc
JAVADOC_OPTIONS := -use -keywords -notimestamp \
-serialwarn -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
-encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
-splitIndex --system none -javafx --expand-requires transitive \
--override-methods=summary

# The reference options must stay stable to allow for comparisons across the
# development cycle.
REFERENCE_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
-serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
-encoding ISO-8859-1 -breakiterator -splitIndex --system none \
-html5 -javafx --expand-requires transitive

# Should we add DRAFT stamps to the generated javadoc?
Expand Down
Expand Up @@ -403,16 +403,6 @@ public JavaFileManager getFileManager() {
return docEnv.getJavaFileManager();
}

@Override
public boolean showMessage(DocTreePath path, String key) {
return (path == null || !haveDocLint());
}

@Override
public boolean showMessage(Element e, String key) {
return (e == null || !haveDocLint());
}

@Override
protected boolean finishOptionSettings0() throws DocletException {
if (options.docEncoding() == null) {
Expand Down
Expand Up @@ -1054,10 +1054,12 @@ public Content seeTagToContent(Element element, DocTree see, TagletWriterImpl.Co
(labelContent.isEmpty() ? text : labelContent));
} else {
// No cross link found so print warning
messages.warning(ch.getDocTreePath(see),
"doclet.see.class_or_package_not_found",
"@" + tagName,
seeText);
if (!configuration.isDocLintReferenceGroupEnabled()) {
messages.warning(ch.getDocTreePath(see),
"doclet.see.class_or_package_not_found",
"@" + tagName,
seeText);
}
return invalidTagOutput(resources.getText("doclet.tag.invalid", tagName),
Optional.of(labelContent.isEmpty() ? text: labelContent));
}
Expand Down Expand Up @@ -1107,9 +1109,11 @@ public Content seeTagToContent(Element element, DocTree see, TagletWriterImpl.Co
ch.getDocTreePath(see), "doclet.see.class_or_package_not_accessible",
tagName, utils.getFullyQualifiedName(containing));
} else {
messages.warning(
ch.getDocTreePath(see), "doclet.see.class_or_package_not_found",
tagName, seeText);
if (!configuration.isDocLintReferenceGroupEnabled()) {
messages.warning(
ch.getDocTreePath(see), "doclet.see.class_or_package_not_found",
tagName, seeText);
}
}
}
if (configuration.currentTypeElement != containing) {
Expand Down Expand Up @@ -1599,7 +1603,9 @@ public Boolean visitErroneous(ErroneousTree node, Content c) {
Matcher m = Pattern.compile("(?i)\\{@([a-z]+).*").matcher(body);
String tagName = m.matches() ? m.group(1) : null;
if (tagName == null) {
messages.warning(dtp, "doclet.tag.invalid_input", body);
if (!configuration.isDocLintSyntaxGroupEnabled()) {
messages.warning(dtp, "doclet.tag.invalid_input", body);
}
result.add(invalidTagOutput(resources.getText("doclet.tag.invalid_input", body),
Optional.empty()));
} else {
Expand Down
Expand Up @@ -28,7 +28,6 @@

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.InvalidPathException;
import java.nio.file.Path;
import java.util.ArrayList;
Expand Down Expand Up @@ -60,7 +59,6 @@
import javax.tools.StandardJavaFileManager;

import com.sun.source.tree.CompilationUnitTree;
import com.sun.source.util.DocTreePath;
import com.sun.source.util.TreePath;
import com.sun.tools.javac.util.DefinedBy;
import com.sun.tools.javac.util.DefinedBy.Api;
Expand All @@ -74,7 +72,6 @@
import jdk.javadoc.internal.doclets.toolkit.util.Comparators;
import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileFactory;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.Extern;
import jdk.javadoc.internal.doclets.toolkit.util.Group;
import jdk.javadoc.internal.doclets.toolkit.util.MetaKeywords;
Expand All @@ -85,6 +82,7 @@
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberCache;
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
import jdk.javadoc.internal.doclint.DocLint;
import jdk.javadoc.internal.doclint.Env;

/**
* Configure the output based on the options. Doclets should subclass
Expand Down Expand Up @@ -640,10 +638,6 @@ public boolean isGeneratedDoc(TypeElement te) {
*/
public abstract JavaFileManager getFileManager();

public abstract boolean showMessage(DocTreePath path, String key);

public abstract boolean showMessage(Element e, String key);

/*
* Splits the elements in a collection to its individual
* collection.
Expand Down Expand Up @@ -803,8 +797,20 @@ public void initDocLint(List<String> opts, Set<String> customTagNames) {
doclintOpts.toArray(new String[0]));
}

public boolean haveDocLint() {
return (doclint != null);
public boolean isDocLintReferenceGroupEnabled() {
return isDocLintGroupEnabled(jdk.javadoc.internal.doclint.Messages.Group.REFERENCE);
}

public boolean isDocLintSyntaxGroupEnabled() {
return isDocLintGroupEnabled(jdk.javadoc.internal.doclint.Messages.Group.SYNTAX);
}

private boolean isDocLintGroupEnabled(jdk.javadoc.internal.doclint.Messages.Group group) {
// Use AccessKind.PUBLIC as a stand-in, since it is not common to
// set DocLint options per access kind (as is common with javac.)
// A more sophisticated solution might be to derive the access kind from the
// element owning the comment, and its enclosing elements.
return doclint != null && doclint.isGroupEnabled(group, Env.AccessKind.PUBLIC);
}
//</editor-fold>
}
Expand Up @@ -143,9 +143,7 @@ public void warning(String key, Object... args) {
* @param args optional arguments to be replaced in the message
*/
public void warning(DocTreePath path, String key, Object... args) {
if (configuration.showMessage(path, key)) {
report(WARNING, path, resources.getText(key, args));
}
report(WARNING, path, resources.getText(key, args));
}

/**
Expand All @@ -170,9 +168,7 @@ public void warning(DocTreePath path, int start, int pos, int end, String key, O
* @param args optional arguments to be replaced in the message
*/
public void warning(Element e, String key, Object... args) {
if (configuration.showMessage(e, key)) {
report(WARNING, e, resources.getText(key, args));
}
report(WARNING, e, resources.getText(key, args));
}

/**
Expand Down
Expand Up @@ -222,7 +222,9 @@ private Content processParamTags(Element e,
case TYPE_PARAMETER -> "doclet.TypeParameters_warn";
case RECORD_COMPONENT -> "doclet.RecordComponents_warn";
};
messages.warning(ch.getDocTreePath(dt), key, paramName);
if (!writer.configuration().isDocLintReferenceGroupEnabled()) {
messages.warning(ch.getDocTreePath(dt), key, paramName);
}
}
String rank = rankMap.get(name);
if (rank != null) {
Expand All @@ -232,7 +234,9 @@ private Content processParamTags(Element e,
case TYPE_PARAMETER -> "doclet.TypeParameters_dup_warn";
case RECORD_COMPONENT -> "doclet.RecordComponents_dup_warn";
};
messages.warning(ch.getDocTreePath(dt), key, paramName);
if (!writer.configuration().isDocLintReferenceGroupEnabled()) {
messages.warning(ch.getDocTreePath(dt), key, paramName);
}
} else {
documented.put(rank, dt);
}
Expand Down
Expand Up @@ -96,7 +96,7 @@ public Content getAllBlockTagOutput(Element holder, TagletWriter writer) {
// Make sure we are not using @return tag on method with void return type.
TypeMirror returnType = utils.getReturnType(writer.getCurrentPageElement(), (ExecutableElement) holder);
if (returnType != null && utils.isVoid(returnType)) {
if (!tags.isEmpty()) {
if (!tags.isEmpty() && !writer.configuration().isDocLintReferenceGroupEnabled()) {
messages.warning(holder, "doclet.Return_tag_on_void_method");
}
return null;
Expand Down
Expand Up @@ -384,6 +384,10 @@ public boolean isValidOption(String opt) {
return false;
}

public boolean isGroupEnabled(Messages.Group group, Env.AccessKind accessKind) {
return env.messages.isEnabled(group, accessKind);
}

private String localize(String code, Object... args) {
Messages m = (env != null) ? env.messages : new Messages(null);
return m.localize(code, args);
Expand Down
Expand Up @@ -104,6 +104,10 @@ void setStatsEnabled(boolean b) {
stats.setEnabled(b);
}

boolean isEnabled(Group group, Env.AccessKind ak) {
return options.isEnabled(group, ak);
}

void reportStats(PrintWriter out) {
stats.report(out);
}
Expand Down

0 comments on commit 59e9700

Please sign in to comment.