JDK-8296175: Output warning if generated docs contain diagnostic markers

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java

@@ -335,6 +335,10 @@ protected void generateOtherFiles(ClassTree classTree)
                     DocPaths.RESOURCE_FILES.resolve(DocPaths.JQUERY_UI_CSS), false);        }
 
         copyLegalFiles(options.createIndex());
+        // Print a notice if the documentation contains diagnostic markers
+        if (messages.containsDiagnosticMarkers()) {
+            messages.notice("doclet.contains.diagnostic.markers");
+        }
     }
 
     @Override

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

@@ -1611,6 +1611,7 @@ private boolean shouldRedirectRelativeLinks(Element element) {
      * @return the output
      */
     public Content invalidTagOutput(String summary, Optional<Content> detail) {
+        messages.setContainsDiagnosticMarkers();
         if (detail.isEmpty() || detail.get().isEmpty()) {
             return HtmlTree.SPAN(HtmlStyle.invalidTag, Text.of(summary));
         }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Messages.java

@@ -47,6 +47,7 @@ public class Messages {
     private final BaseConfiguration configuration;
     private final Resources resources;
     private final Reporter reporter;
+    private boolean containsDiagnosticMarkers = false;
 
     /**
      * Creates a {@code Messages} object to provide standardized access to
@@ -212,6 +213,21 @@ public void notice(String key, Object... args) {
         }
     }
 
+    /**
+     * {@return true if the generated documentation contains one or more diagnostic markers
+     * for invalid input}
+     */
+    public boolean containsDiagnosticMarkers() {
+        return containsDiagnosticMarkers;
+    }
+
+    /**
+     * Sets the flag for documentation containing a diagnostic marker for invalid input.
+     */
+    public void setContainsDiagnosticMarkers() {
+        this.containsDiagnosticMarkers = true;
+    }
+
     // ***** Internal support *****
 
     private void report(Diagnostic.Kind k, String msg) {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties

@@ -262,6 +262,8 @@ doclet.urlRedirected=URL {0} was redirected to {1} -- Update the command-line op
 doclet.unexpectedRedirect=Unexpected redirection for URL {0} to {1}
 doclet.duplicate.comment.for.property=Duplicate comment for property.\n\
   Remove the comment on the property field or on this method to suppress this warning.
+doclet.contains.diagnostic.markers=\
+ The generated documentation contains diagnostic markers for invalid input.
 
 #Documentation for Enums
 doclet.enum_values_doc.fullbody=\

test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2024, 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
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug 8004834 8007610 8129909 8182765 8247815
+ * @bug 8004834 8007610 8129909 8182765 8247815 8296175
  * @summary Add doclint support into javadoc
  * @modules jdk.compiler/com.sun.tools.javac.main
  */
@@ -117,7 +117,10 @@ private enum Message {
         // javadoc messages for bad options
         OPT_BADARG(ERROR, "error: Invalid argument for -Xdoclint option"),
         OPT_BADQUAL(ERROR, "error: Access qualifiers not permitted for -Xdoclint arguments"),
-        OPT_BADPACKAGEARG(ERROR, "error: Invalid argument for -Xdoclint/package option");
+        OPT_BADPACKAGEARG(ERROR, "error: Invalid argument for -Xdoclint/package option"),
+
+        // javadoc notice about markers for invalid input
+        JD_NOTE_MARK(NOTE, "The generated documentation contains diagnostic markers for invalid input.");
 
         final Diagnostic.Kind kind;
         final String text;
@@ -151,19 +154,22 @@ void run() throws Exception {
 
             test(List.of(htmlVersion),
                     Main.Result.ERROR,
-                    EnumSet.of(Message.DL_ERR10A, Message.DL_WRN14A));
+                    EnumSet.of(Message.DL_ERR10A, Message.DL_WRN14A,
+                            Message.JD_NOTE_MARK));
 
             test(List.of(htmlVersion, rawDiags),
                     Main.Result.ERROR,
-                    EnumSet.of(Message.DL_ERR10, Message.DL_WRN14));
+                    EnumSet.of(Message.DL_ERR10, Message.DL_WRN14,
+                            Message.JD_NOTE_MARK));
 
 //            test(List.of("-Xdoclint:none"),
 //                    Main.Result.OK,
 //                    EnumSet.of(Message.JD_WRN10, Message.JD_WRN13));
 
             test(List.of(htmlVersion, rawDiags, "-Xdoclint"),
                     Main.Result.ERROR,
-                    EnumSet.of(Message.DL_ERR10, Message.DL_WRN14));
+                    EnumSet.of(Message.DL_ERR10, Message.DL_WRN14,
+                            Message.JD_NOTE_MARK));
 
             test(List.of(htmlVersion, rawDiags, "-Xdoclint:all/public"),
                     Main.Result.ERROR,
@@ -175,19 +181,21 @@ void run() throws Exception {
 
             test(List.of(htmlVersion, rawDiags, "-Xdoclint:missing"),
                     Main.Result.OK,
-                    EnumSet.of(Message.DL_WRN14));
+                    EnumSet.of(Message.DL_WRN14, Message.JD_NOTE_MARK));
 
             test(List.of(htmlVersion, rawDiags, "-private"),
                     Main.Result.ERROR,
-                    EnumSet.of(Message.DL_ERR6, Message.DL_ERR10, Message.DL_WRN14));
+                    EnumSet.of(Message.DL_ERR6, Message.DL_ERR10,
+                            Message.DL_WRN14, Message.JD_NOTE_MARK));
 
             test(List.of(htmlVersion, rawDiags, "-Xdoclint:missing,syntax", "-private"),
                     Main.Result.ERROR,
-                    EnumSet.of(Message.DL_ERR6, Message.DL_WRN14));
+                    EnumSet.of(Message.DL_ERR6, Message.DL_WRN14,
+                            Message.JD_NOTE_MARK));
 
             test(List.of(htmlVersion, rawDiags, "-Xdoclint:reference"),
                     Main.Result.ERROR,
-                    EnumSet.of(Message.DL_ERR10));
+                    EnumSet.of(Message.DL_ERR10, Message.JD_NOTE_MARK));
 
             test(List.of(htmlVersion, rawDiags, "-Xdoclint:badarg"),
                     Main.Result.ERROR,
@@ -199,12 +207,13 @@ void run() throws Exception {
             test(List.of(htmlVersion, rawDiags),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR_P1TEST, Message.DL_ERR_P2TEST,
-                            Message.DL_WARN_P1TEST, Message.DL_WARN_P2TEST));
+                            Message.DL_WARN_P1TEST, Message.DL_WARN_P2TEST, Message.JD_NOTE_MARK));
 
             test(List.of(htmlVersion, rawDiags, "-Xdoclint/package:p1"),
                     Main.Result.ERROR,
                     EnumSet.of(Message.DL_ERR_P1TEST,
-                            Message.DL_WARN_P1TEST));
+                            Message.DL_WARN_P1TEST,
+                            Message.JD_NOTE_MARK));
 
             test(List.of(htmlVersion, rawDiags, "-Xdoclint/package:*p"),
                     Main.Result.ERROR,