infernap12/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2026-01-28 12:09:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

8296175: Output warning if generated docs contain diagnostic markers

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Hannes Wallnöfer 2024-04-26 19:59:57 +00:00
parent a920af233a
commit aee91fbc70
5 changed files with 44 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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

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

@ -1611,6 +1611,7 @@ public abstract class HtmlDocletWriter {
* @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));
}

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

@ -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) {

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

@ -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=\

33
test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java
View File

@ -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,