8268831: Improve javadoc tool handling of streams.

Reviewed-by: hannesw
This commit is contained in:
Jonathan Gibbons 2022-01-19 17:56:25 +00:00
parent e20c6bf972
commit 610a12904d
5 changed files with 48 additions and 58 deletions
src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2022, 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
@ -793,7 +793,7 @@ public class ElementsTable {
Collection<ModulePackage> collection,
boolean recurse) throws ToolException {
for (ModulePackage modpkg : collection) {
toolEnv.notice("main.Loading_source_files_for_package", modpkg.toString());
toolEnv.printInfo("main.Loading_source_files_for_package", modpkg.toString());
List<JavaFileObject> files = getFiles(modpkg, recurse);
if (files.isEmpty()) {
String text = log.getText("main.no_source_files_for_package",

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2022, 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
@ -292,12 +292,6 @@ public class JavadocLog extends Log implements Reporter {
report(dt, flags, ds, dp, message);
}
private int getSourcePos(DocTreePath path, int offset) {
DCTree.DCDocComment docComment = (DCTree.DCDocComment) path.getDocComment();
DCTree tree = (DCTree) path.getLeaf();
return docComment.getSourcePosition(tree.getStartPosition() + offset);
}
@Override // Reporter
public void print(Kind kind, Element element, String message) {
DiagnosticType dt = getDiagnosticType(kind);
@ -450,22 +444,27 @@ public class JavadocLog extends Log implements Reporter {
}
/**
* Prints a "notice" message to the standard writer.
*
* @param key the resource key for the message
* @param args the arguments for the message
*/
public void noticeUsingKey(String key, Object... args) {
printRawLines(getStandardWriter(), getText(key, args));
}
/**
* Prints a "notice" message to the standard writer.
* Prints a "notice" message.
*
* @param message the message
*/
public void notice(String message) {
printRawLines(getStandardWriter(), message);
public void printNote(String message) {
// Ideally, for consistency with errors and warnings, we would use the following:
// report(Kind.NOTE, null, null, message);
// but the default formatting in Log for Kind.NOTE is to prefix the line with "Note:"
// which is undesirable and inconsistent with existing javadoc output.
// For now, to avoid the prefix, we write directly to the underlying stream.
printRawLines(WriterKind.NOTICE, message);
}
/**
* Prints a "notice" message.
*
* @param key the resource key for the message
* @param args the arguments for the message
*/
public void printNoteUsingKey(String key, Object... args) {
printNote(getText(key, args));
}
/**

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2022, 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
@ -207,7 +207,7 @@ public class JavadocTool extends com.sun.tools.javac.main.JavaCompiler {
}
// Enter symbols for all files
toolEnv.notice("main.Building_tree");
toolEnv.printInfo("main.Building_tree");
javadocEnter.main(allTrees.toList());
if (log.hasErrors()) {
@ -284,7 +284,7 @@ public class JavadocTool extends com.sun.tools.javac.main.JavaCompiler {
for (JavaFileObject fo: files) {
if (uniquefiles.add(fo)) { // ignore duplicates
if (trace)
toolEnv.notice("main.Loading_source_file", fo.getName());
toolEnv.printInfo("main.Loading_source_file", fo.getName());
trees.append(parse(fo));
}
}

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2022, 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
@ -196,7 +196,7 @@ public class Start {
}
private void showUsage(String headerKey, ToolOption.Kind kind, String footerKey) {
log.noticeUsingKey(headerKey);
showLinesUsingKey(headerKey);
showToolOptions(kind);
// let doclet print usage information
@ -205,12 +205,13 @@ public class Start {
? Option.Kind.EXTENDED
: Option.Kind.STANDARD);
}
if (footerKey != null)
log.noticeUsingKey(footerKey);
if (footerKey != null) {
showLinesUsingKey(footerKey);
}
}
private void showVersion(String labelKey, String value) {
log.noticeUsingKey(labelKey, log.programName, value);
showLinesUsingKey(labelKey, log.programName, value);
}
private void showToolOptions(ToolOption.Kind kind) {
@ -253,7 +254,7 @@ public class Start {
if (options.isEmpty()) {
return;
}
log.noticeUsingKey("main.doclet.usage.header", name);
showLinesUsingKey("main.doclet.usage.header", name);
Comparator<Doclet.Option> comp = new Comparator<Doclet.Option>() {
final Collator collator = Collator.getInstance(Locale.US);
@ -308,22 +309,30 @@ public class Start {
if (synopses.length() < DEFAULT_SYNOPSIS_WIDTH
&& !description.contains("\n")
&& (SMALL_INDENT.length() + DEFAULT_SYNOPSIS_WIDTH + 1 + description.length() <= DEFAULT_MAX_LINE_LENGTH)) {
log.notice(String.format(COMPACT_FORMAT, synopses, description));
showLines(String.format(COMPACT_FORMAT, synopses, description));
return;
}
// If option synopses fit on a single line of reasonable length, show that;
// otherwise, show 1 per line
if (synopses.length() <= DEFAULT_MAX_LINE_LENGTH) {
log.notice(SMALL_INDENT + synopses);
showLines(SMALL_INDENT + synopses);
} else {
for (String name: names) {
log.notice(SMALL_INDENT + name + parameters);
showLines(SMALL_INDENT + name + parameters);
}
}
// Finally, show the description
log.notice(LARGE_INDENT + description.replace("\n", "\n" + LARGE_INDENT));
showLines(LARGE_INDENT + description.replace("\n", "\n" + LARGE_INDENT));
}
private void showLinesUsingKey(String key, Object... args) {
showLines(log.getText(key, args));
}
private void showLines(String message) {
log.printRawLines(Log.WriterKind.STDOUT, message);
}

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 2022, 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
@ -191,28 +191,14 @@ public class ToolEnvironment {
}
/**
* Print a notice, iff <em>quiet</em> is not specified.
* Prints a notice unless {@code -quiet} was specified.
*
* @param key selects message from resource
*/
public void notice(String key) {
if (quiet) {
return;
public void printInfo(String key, Object... args) {
if (!quiet) {
log.printNoteUsingKey(key, args);
}
JavadocLog.printRawLines(log.getDiagnosticWriter(), log.getText(key));
}
/**
* Print a notice, iff <em>quiet</em> is not specified.
*
* @param key selects message from resource
* @param a1 first argument
*/
public void notice(String key, String a1) {
if (quiet) {
return;
}
JavadocLog.printRawLines(log.getDiagnosticWriter(), log.getText(key, a1));
}
TreePath getTreePath(JCCompilationUnit tree) {
@ -247,8 +233,4 @@ public class ToolEnvironment {
public Env<AttrContext> getEnv(ClassSymbol tsym) {
return enter.getEnv(tsym);
}
public boolean isQuiet() {
return quiet;
}
}