diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java index aedaee2b828..17867e368bf 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java @@ -335,6 +335,10 @@ public class HtmlDoclet extends AbstractDoclet { 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 diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java index 25ec603a064..3e461dc3e74 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java @@ -1611,6 +1611,7 @@ public abstract class HtmlDocletWriter { * @return the output */ public Content invalidTagOutput(String summary, Optional detail) { + messages.setContainsDiagnosticMarkers(); if (detail.isEmpty() || detail.get().isEmpty()) { return HtmlTree.SPAN(HtmlStyle.invalidTag, Text.of(summary)); } diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Messages.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Messages.java index 9183804ddc6..576bf64e751 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Messages.java +++ b/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 class Messages { } } + /** + * {@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) { diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties index 7c5b43d35df..859289ff8bd 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties +++ b/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=\ diff --git a/test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java b/test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java index 4af51070468..ff6e5ec8dff 100644 --- a/test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java +++ b/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 @@ public class DocLintTest { // 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,11 +154,13 @@ public class DocLintTest { 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, @@ -163,7 +168,8 @@ public class DocLintTest { 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 @@ public class DocLintTest { 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 @@ public class DocLintTest { 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,