8268831: Improve javadoc tool handling of streams.

Reviewed-by: hannesw

Author: jonathan-gibbons

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java

@@ -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 @@ private void addFilesForParser(Collection<JavaFileObject> result,
             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",

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocLog.java

@@ -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 void print(Diagnostic.Kind kind, DocTreePath path, int start, int pos, in
         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 void printWarningUsingKey(Element element, String key, Object... args) {
     }
 
     /**
-     * Prints a "notice" message to the standard writer.
+     * Prints a "notice" message.
      *
-     * @param key  the resource key for the message
-     * @param args the arguments for the message
+     * @param message the message
      */
-    public void noticeUsingKey(String key, Object... args) {
-        printRawLines(getStandardWriter(), getText(key, args));
+    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 to the standard writer.
+     * Prints a "notice" message.
      *
-     * @param message the message
+     * @param key the resource key for the message
+     * @param args the arguments for the message
      */
-    public void notice(String message) {
-        printRawLines(getStandardWriter(), message);
+    public void printNoteUsingKey(String key, Object... args) {
+        printNote(getText(key, args));
     }
 
     /**

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocTool.java

@@ -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 DocletEnvironment getEnvironment(ToolOptions toolOptions,
             }
 
             // 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 @@ private void parse(Iterable<? extends JavaFileObject> files, ListBuffer<JCCompil
         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));
             }
         }

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

@@ -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 @@ private void showUsage() {
     }
 
     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 @@ private void showUsage(String headerKey, ToolOption.Kind kind, String footerKey)
                     ? 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 @@ private void showDocletOptions(Option.Kind kind) {
         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 @@ void showOption(List<String> names, String parameters, String description) {
         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);
     }
 
 

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ToolEnvironment.java

@@ -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 Kind getFileKind(TypeElement te) {
     }
 
     /**
-     * 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 com.sun.tools.javac.code.Types getTypes() {
     public Env<AttrContext> getEnv(ClassSymbol tsym) {
         return enter.getEnv(tsym);
     }
-
-    public boolean isQuiet() {
-        return quiet;
-    }
 }