Skip to content
Permalink
Browse files
8223355: Redundant output by javadoc
Reviewed-by: hannesw
  • Loading branch information
jonathan-gibbons committed Feb 23, 2021
1 parent d2b9c22 commit 53b15453d91fac82ef64ffd679ea4652ef3d7b48
Showing 4 changed files with 135 additions and 16 deletions.
@@ -198,7 +198,6 @@ private void handleHtmlFile(DocFile srcfile, DocPath dstPath) throws DocFileIOEx
PackageElement pkg = dfElement.getPackageElement();

HtmlDocletWriter docletWriter = new DocFileWriter(configuration, dfilePath, element, pkg);
configuration.messages.notice("doclet.Generating_0", docletWriter.filename.getPath());

List<? extends DocTree> localTags = getLocalHeaderTags(utils.getPreamble(dfElement));
Content localTagsContent = docletWriter.commentTagsToContent(null, dfElement, localTags, false);
@@ -267,17 +267,22 @@ protected abstract void generateClassFiles(SortedSet<TypeElement> arr, ClassTree
*/
protected void generateClassFiles(ClassTree classtree)
throws DocletException {

SortedSet<TypeElement> classes = new TreeSet<>(utils.comparators.makeGeneralPurposeComparator());

// handle classes specified as files on the command line
for (PackageElement pkg : configuration.typeElementCatalog.packages()) {
generateClassFiles(configuration.typeElementCatalog.allClasses(pkg), classtree);
classes.addAll(configuration.typeElementCatalog.allClasses(pkg));
}

// handle classes specified in m odules and packages on the command line
// handle classes specified in modules and packages on the command line
SortedSet<PackageElement> packages = new TreeSet<>(utils.comparators.makePackageComparator());
packages.addAll(configuration.getSpecifiedPackageElements());
configuration.modulePackages.values().stream().forEach(packages::addAll);
for (PackageElement pkg : packages) {
generateClassFiles(utils.getAllClasses(pkg), classtree);
classes.addAll(utils.getAllClasses(pkg));
}

generateClassFiles(classes, classtree);
}
}
@@ -0,0 +1,68 @@
/*
* Copyright (c) 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/

/*
* @test
* @bug 8223355
* @summary Redundant output by javadoc
* @library /tools/lib ../../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* @build toolbox.ToolBox javadoc.tester.*
* @run main TestGeneratedClasses
*/

import java.nio.file.Path;

import javadoc.tester.JavadocTester;
import toolbox.ToolBox;

public class TestGeneratedClasses extends JavadocTester {

public static void main(String... args) throws Exception {
TestGeneratedClasses tester = new TestGeneratedClasses();
tester.runTests(m -> new Object[]{Path.of(m.getName())});
}

ToolBox tb = new ToolBox();

@Test
public void testClasses(Path base) throws Exception {
Path src = base.resolve("src");
Path src_m = src.resolve("m");
tb.writeJavaFiles(src_m,
"module m { exports p; }",
"package p; public class C { }");

javadoc("-d", base.resolve("out").toString(),
"--source-path", src_m.toString(),
"-Xdoclint:none",
"--module", "m");

// verify that C.html is only generated once
checkOutput(Output.OUT, true,
"""
Building tree for all the packages and classes...
Generating testClasses/out/m/p/C.html...
Generating testClasses/out/m/p/package-summary.html...""");
}
}
@@ -54,6 +54,8 @@
import java.util.Map;
import java.util.Objects;
import java.util.function.Function;
import java.util.regex.Matcher;
import java.util.regex.Pattern;


/**
@@ -233,6 +235,7 @@ void check(File dir) {

private boolean automaticCheckAccessibility = true;
private boolean automaticCheckLinks = true;
private boolean automaticCheckUniqueOUT = true;

/** The current subtest number. Incremented when checking(...) is called. */
private int numTestsRun = 0;
@@ -318,18 +321,10 @@ public void javadoc(String... args) {
String encodingArg = null;
for (int i = 0; i < args.length - 2; i++) {
switch (args[i]) {
case "-d":
outputDir = new File(args[++i]);
break;
case "-charset":
charsetArg = args[++i];
break;
case "-docencoding":
docencodingArg = args[++i];
break;
case "-encoding":
encodingArg = args[++i];
break;
case "-d" -> outputDir = new File(args[++i]);
case "-charset" -> charsetArg = args[++i];
case "-docencoding" -> docencodingArg = args[++i];
case "-encoding" -> encodingArg = args[++i];
}
}

@@ -386,6 +381,9 @@ public void javadoc(String... args) {
if (automaticCheckAccessibility) {
checkAccessibility();
}
if (automaticCheckUniqueOUT) {
checkUnique(Output.OUT, "^[A-Z][a-z]+ing ", true);
}
}
}

@@ -413,6 +411,13 @@ public void setAutomaticCheckLinks(boolean b) {
automaticCheckLinks = b;
}

/**
* Sets whether or not to perform an automatic call of checkUnique(OUT).
*/
public void setAutomaticCheckUniqueOUT(boolean b) {
automaticCheckUniqueOUT = b;
}

/**
* The exit codes returned by the javadoc tool.
* @see jdk.javadoc.internal.tool.Main.Result
@@ -525,6 +530,48 @@ private void checkOutput(String path, String fileString, boolean expectedFound,
}
}

/**
* Checks that there are no duplicate lines in one of the streams written by javadoc.
* @param output the output stream to check
*/
public void checkUnique(Output output) {
checkUnique(output, ".*", true);
}

/**
* Checks that there are no duplicate lines that either match or don't match a given patter,
* in one of the streams written by javadoc.
* @param output the output stream to check
* @param pattern a pattern to filter the lines to be checked
* @param select if {@code true}, lines that match the pattern will be checked for uniqueness;
* if {@code false}, lines that do not match the pattern will be checked
*/
public void checkUnique(Output output, String pattern, boolean select) {
checking("checkUnique");
Pattern filter = Pattern.compile(pattern);
Matcher m = filter.matcher("");
Map<String, Integer> linesSofar = new HashMap<>();
int lineNumber = 0;
int duplicates = 0;
for (String line : getOutputLines(output)) {
m.reset(line);
if (m.find() == select) {
Integer prev = linesSofar.putIfAbsent(line, ++lineNumber);
if (prev != null) {
out.println("duplicate line detected on line " + lineNumber
+ "; first occurrence on line " + prev);
out.println("line: " + line);
duplicates++;
}
}
}
if (duplicates == 0) {
passed("All lines are unique");
} else {
failed(duplicates + " duplicate lines found");
}
}

/**
* Performs some structural accessibility checks on the files generated by the most
* recent run of javadoc.

1 comment on commit 53b1545

@openjdk-notifier
Copy link

@openjdk-notifier openjdk-notifier bot commented on 53b1545 Feb 23, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.