Skip to content

8274211: Test man page that options are documented #1782

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.

Sign up for GitHub

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

Closed
GoeLin wants to merge 1 commit into from
Closed

8274211: Test man page that options are documented #1782

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
287 changes: 287 additions & 0 deletions test/langtools/jdk/javadoc/tool/CheckManPageOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,287 @@
/*
* 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 8274211
* @summary Test man page that options are documented
* @modules jdk.javadoc/jdk.javadoc.internal.tool:+open
* @run main CheckManPageOptions
*/

import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.StandardDoclet;
import jdk.javadoc.internal.tool.ToolOptions;

import java.io.IOException;
import java.io.PrintStream;
import java.lang.reflect.Constructor;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Locale;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

/**
* Checks the set of options found by fuzzy-parsing the troff or Markdown versions
* of the javadoc man page against the set of options declared in the source code.
*/
public class CheckManPageOptions {
public static void main(String... args) throws Exception {
new CheckManPageOptions().run(args);
}

static final PrintStream out = System.err;

// FIXME: JDK-8274295, JDK-8266666
List<String> MISSING_IN_MAN_PAGE = List.of(
"--legal-notices",
"--link-platform-properties",
"--no-platform-links",
"--since",
"--since-label",
"--snippet-path");

void run(String... args) throws Exception {
var file = args.length == 0 ? findDefaultFile() : Path.of(args[0]);
out.println("File: " + file);
out.println();

var manPageOptions = getManPageOptions(file);
out.println("Man page options: " + manPageOptions);
out.println();

var toolOptions = getToolOptions();
out.println("ToolOptions: " + toolOptions);
out.println();

var docletOptions = getDocletOptions();
out.println("DocletOptions: " + docletOptions);
out.println();

var toolDocletOnly = new TreeSet<String>();
toolDocletOnly.addAll(toolOptions);
toolDocletOnly.addAll(docletOptions);
toolDocletOnly.removeAll(manPageOptions);
toolDocletOnly.removeAll(MISSING_IN_MAN_PAGE);
if (!toolDocletOnly.isEmpty()) {
error("The following options are defined by the tool or doclet, but not defined in the man page:\n"
+ toSimpleList(toolDocletOnly));
}

var manPageOnly = new TreeSet<String>();
manPageOnly.addAll(manPageOptions);
manPageOnly.removeAll(toolOptions);
manPageOnly.removeAll(docletOptions);
if (!manPageOnly.isEmpty()) {
error("The following options are defined in the man page, but not defined by the tool or doclet:\n"
+ toSimpleList(manPageOnly));
}

if (!MISSING_IN_MAN_PAGE.isEmpty()) {
var notMissing = new TreeSet<>(MISSING_IN_MAN_PAGE);
notMissing.retainAll(manPageOptions);
if (!notMissing.isEmpty()) {
error("The following options were declared as missing, but were found on the man page:\n"
+ toSimpleList(notMissing));
}

out.println("NOTE: the following options are currently excluded and need to be documented in the man page:");
out.println(toSimpleList(MISSING_IN_MAN_PAGE));
}

if (errors > 0) {
out.println(errors + " errors found");
throw new Exception(errors + " errors found");
}
}

int errors = 0;
void error(String message) {
("Error: " + message).lines().forEach(out::println);
errors++;
}

String toSimpleList(Collection<String> items) {
return items.stream().collect(Collectors.joining(", ", " ", ""));
}

Path findDefaultFile() {
return findRootDir().resolve("src/jdk.javadoc/share/man/javadoc.1");
}

Path findRootDir() {
Path dir = Path.of(System.getProperty("test.src", ".")).toAbsolutePath();
while (dir != null) {
if (Files.exists(dir.resolve("src"))) {
return dir;
} else {
Path openDir = dir.resolve("open");
if (Files.exists(openDir.resolve("src"))) {
return openDir;
}
}
dir = dir.getParent();
}
throw new IllegalStateException("cannot find root dir");
}

List<String> getToolOptions() throws Error {
try {
Class<ToolOptions> toolOptionsClass = ToolOptions.class;

Constructor<ToolOptions> constr = toolOptionsClass.getDeclaredConstructor();
constr.setAccessible(true);

Method getSupportedOptions = toolOptionsClass.getMethod("getSupportedOptions");
Class<?> toolOptionClass = List.of(toolOptionsClass.getDeclaredClasses()).stream()
.filter(c -> c.getSimpleName().equals("ToolOption"))
.findFirst()
.orElseThrow();

Field kindField = toolOptionClass.getDeclaredField("kind");
kindField.setAccessible(true);
Method getNames = toolOptionClass.getDeclaredMethod("getNames");
getNames.setAccessible(true);

ToolOptions t = constr.newInstance();
var list = new ArrayList<String>();
var options = (List<?>) getSupportedOptions.invoke(t);
for (var option : options) {
Object kind = kindField.get(option);
if (kind.toString().equals("HIDDEN")) {
continue;
}

@SuppressWarnings("unchecked")
var oNames = (List<String>) getNames.invoke(option);
oNames.stream()
.filter(o -> !o.equals("@"))
.forEach(list::add);
}
return list;
} catch (ReflectiveOperationException e) {
throw new Error(e);
}
}

List<String> getDocletOptions() {
StandardDoclet d = new StandardDoclet();
d.init(Locale.getDefault(), null);
return getDocletOptions(d);
}

List<String> getDocletOptions(Doclet d) {
return d.getSupportedOptions().stream()
.filter(o -> o.getKind() != Doclet.Option.Kind.OTHER)
.flatMap(o -> o.getNames().stream())
.map(n -> n.replaceAll(":$", ""))
.toList();
}

List<String> getManPageOptions(Path file) throws IOException {
String page = Files.readString(file);
String name = file.getFileName().toString();
String extn = name.substring(name.lastIndexOf('.'));
return switch (extn) {
case ".1" -> parseNRoff(page);
case ".md" -> parseMarkdown(page);
default -> throw new IllegalArgumentException(file.toString());
};
}

List<String> parseNRoff(String page) {
var list = new ArrayList<String>();

// In the troff man page, options are defined in one of two forms:
// 1. options delegated to javac appear in pairs of lines of the form
// .IP \[bu] 2
// \f[CB]\-....
// 2. options implemented by the tool or doclet appear in lines of the form
// .B \f[CB]\-...

Pattern p1 = Pattern.compile("\\R" + Pattern.quote(".IP \\[bu] 2") + "\\R" + Pattern.quote("\\f[CB]\\-") + ".*");
Pattern p2 = Pattern.compile("\\R" + Pattern.quote(".B \\f[CB]\\-") + ".*");
Pattern outer = Pattern.compile("(" + p1.pattern() + "|" + p2.pattern() + ")");
Matcher outerMatcher = outer.matcher(page);

// In the defining areas, option names are represented as follows:
// \f[CB]OPTION\f[R] or \f[CB]OPTION:
// where OPTION is the shortest string not containing whitespace or colon,
// and in which all '-' characters are escaped with a single backslash.

Pattern inner = Pattern.compile("\\s\\\\f\\[CB](\\\\-[^ :]+?)(:|\\\\f\\[R])");

while (outerMatcher.find()) {
String lines = outerMatcher.group();
out.println("found:" + lines + "\n");

Matcher innerMatcher = inner.matcher(lines);
while (innerMatcher.find()) {
String option = innerMatcher.group(1).replace("\\-", "-");
list.add(option);
}
}

return list;
}

List<String> parseMarkdown(String page) {
var list = new ArrayList<String>();
// In the Markdown man page, options are defined in one of two forms:
// 1. options delegated to javac appear in lines of the form
// - `-...
// 2. options implemented by the tool or doclet appear in lines of the form
// `-...`

Pattern p1 = Pattern.compile("\\R- `-.*");
Pattern p2 = Pattern.compile("\\R`-.*");
Pattern outer = Pattern.compile("(" + p1.pattern() + "|" + p2.pattern() + ")");
Matcher outerMatcher = outer.matcher(page);

// In the defining areas, option names are represented as follows:
// `OPTION`
// where OPTION is the shortest string not containing whitespace or colon
Pattern inner = Pattern.compile("\\s`([^:`]+)");

while (outerMatcher.find()) {
String lines = outerMatcher.group();
out.println("found:" + lines + "\n");

Matcher innerMatcher = inner.matcher(lines);
while (innerMatcher.find()) {
String option = innerMatcher.group(1);
list.add(option);
}
}

return list;
}
}