Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JDK-8249634: doclint should report implicit constructor as missing javadoc comments #4695

Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
@@ -182,10 +182,18 @@ public Void scan(DocCommentTree tree, TreePath p) {
reportMissing("dc.missing.comment");
return null;
}



} else {
if (tree == null) {
if (!isSynthetic() && !isOverridingMethod)
if (isDefaultConstructor()) {
if (isNormalClass(p.getParentPath())) {
reportMissing("dc.default.constructor");
}
} else if (!isOverridingMethod) {
reportMissing("dc.missing.comment");
}
return null;
}
}
@@ -1142,7 +1150,7 @@ private boolean isCheckedException(TypeMirror t) {
|| env.types.isAssignable(t, env.java_lang_RuntimeException));
}

private boolean isSynthetic() {
private boolean isDefaultConstructor() {
switch (env.currElement.getKind()) {
case CONSTRUCTOR:
// A synthetic default constructor has the same pos as the
@@ -1153,6 +1161,14 @@ private boolean isSynthetic() {
return false;
}

private boolean isNormalClass(TreePath p) {
return switch (p.getLeaf().getKind()) {
case ENUM, RECORD -> false;
case CLASS -> true;
default -> throw new IllegalArgumentException(p.getLeaf().getKind().name());
};
}

void markEnclosingTag(Flag flag) {
TagStackItem top = tagStack.peek();
if (top != null)
@@ -1,5 +1,5 @@
#
# Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
# Copyright (c) 2012, 2021, 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
@@ -37,6 +37,7 @@ dc.attr.table.border.not.number = invalid value for attribute "border": {0}
dc.attr.unknown = unknown attribute: {0}
dc.bad.option = bad option: {0}
dc.bad.value.for.option = bad value for option: {0} {1}
dc.default.constructor = use of default constructor, which does not provide a comment
dc.empty = no description for @{0}
dc.entity.invalid = invalid entity &{0};
dc.exception.not.thrown = exception not thrown: {0}
@@ -62,6 +62,7 @@ public class MyClass { }
"-XDaccessInternalAPI",
"-tagletpath", testClasses,
"-taglet", "MyTaglet",
"-Xdoclint:none",
"MyClass.java");
checkExit(Exit.ERROR);

@@ -420,7 +420,7 @@ public class BooleanProperty { }
"--javafx",
"--disable-javafx-strict-checks",
"--no-platform-links",
"-Xdoclint:all",
"-Xdoclint:all,-missing",
"--source-path", "src5",
"pkg");
checkExit(Exit.OK);
@@ -49,11 +49,13 @@ public static void main(String... args) throws Exception {
public void testClass(Path base) throws Exception {
test(base.resolve("class"), """
// no doc comment
public class C { }
public class C {
/** . */ C() { }
}
""",
"""
testClass/class/src/C.java:2: warning: no comment
public class C { }
public class C {
^
""");
}
@@ -65,6 +67,7 @@ public void testExecutable(Path base) throws Exception {
public class C {
// no doc comment
public void m() { }
/** . */ C() { }
}
""",
"""
@@ -81,6 +84,7 @@ public void testField(Path base) throws Exception {
public class C {
// no doc comment
public int f;
/** . */ C() { }
}
""",
"""
@@ -96,12 +100,15 @@ public void testNested(Path base) throws Exception {
/** Class comment. */
public class C {
// no doc comment
public class Nested { }
public class Nested {
/** . */ Nested() { }
}
/** . */ C() { }
}
""",
"""
testNested/nest/src/C.java:4: warning: no comment
public class Nested { }
public class Nested {
^
""");
}
@@ -63,7 +63,7 @@ public static void main(String... args) throws Exception {

final String code =
/* 01 */ "/** Class comment. */\n" +
/* 02 */ "public class Test {\n" +
/* 02 */ "public class Test { /** */ Test() { }\n" +
/* 03 */ " /** Method comment. */\n" +
/* 04 */ " public void method() { }\n" +
/* 05 */ "\n" +
@@ -85,14 +85,14 @@ public static void main(String... args) throws Exception {

final String p1Code =
/* 01 */ "package p1;\n" +
/* 02 */ "public class P1Test {\n" +
/* 02 */ "public class P1Test { /** */ P1Test() { }\n" +
/* 03 */ " /** Syntax < error. */\n" +
/* 04 */ " public void method() { }\n" +
/* 05 */ "}\n";

final String p2Code =
/* 01 */ "package p2;\n" +
/* 02 */ "public class P2Test {\n" +
/* 02 */ "public class P2Test { /** */ P2Test() { }\n" +
/* 03 */ " /** Syntax < error. */\n" +
/* 04 */ " public void method() { }\n" +
/* 05 */ "}\n";
@@ -19,7 +19,7 @@
*/

/** */
public class AccessTest {
public class AccessTest { /** */ AccessTest() { }
/**
* public a < b
*/
@@ -42,7 +42,7 @@ private void private_syntax_error() { }
}

/** */
class AccessTest2 {
class AccessTest2 { /** */ AccessTest2() { }
/**
* public a < b
*/
@@ -4,8 +4,8 @@
* @summary Add new doclint package
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:-accessibility AccessibilityTest.java
* @run main DocLintTester -ref AccessibilityTest.out AccessibilityTest.java
* @run main DocLintTester -Xmsgs:all,-missing,-accessibility AccessibilityTest.java
* @run main DocLintTester -Xmsgs:all,-missing -ref AccessibilityTest.out AccessibilityTest.java
*/

/** */
@@ -4,7 +4,7 @@
* @summary Add new doclint package
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -ref AnchorTest.out AnchorTest.java
* @run main DocLintTester -Xmsgs:all,-missing -ref AnchorTest.out AnchorTest.java
*/

/** */
@@ -4,8 +4,8 @@
* @summary doclint doesn't reset HTML anchors correctly
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -ref AnchorTest2.out AnchorTest2.java AnchorTest2a.java
* @run main DocLintTester -ref AnchorTest2.out AnchorTest2a.java AnchorTest2.java
* @run main DocLintTester -Xmsgs:all,-missing -ref AnchorTest2.out AnchorTest2.java AnchorTest2a.java
* @run main DocLintTester -Xmsgs:all,-missing -ref AnchorTest2.out AnchorTest2a.java AnchorTest2.java
*/

/** */
@@ -2,7 +2,7 @@
* @test /nodynamiccopyright/
* @bug 8266082
* @summary javac should not crash when seeing type annotations in links
* @compile/fail/ref=CrashInAnnotateTest.out -Xdoclint -XDrawDiagnostics CrashInAnnotateTest.java
* @compile/fail/ref=CrashInAnnotateTest.out -Xdoclint:all,-missing -XDrawDiagnostics CrashInAnnotateTest.java
*/

import java.util.List;
@@ -1,11 +1,7 @@
CrashInAnnotateTest.java:10:5: compiler.err.proc.messager: annotations not allowed
CrashInAnnotateTest.java:11:5: compiler.err.proc.messager: syntax error in reference
CrashInAnnotateTest.java:16:5: compiler.err.proc.messager: annotations not allowed
CrashInAnnotateTest.java:18:10: compiler.warn.proc.messager: no comment
CrashInAnnotateTest.java:21:5: compiler.err.proc.messager: syntax error in reference
CrashInAnnotateTest.java:24:5: compiler.err.proc.messager: syntax error in reference
CrashInAnnotateTest.java:25:5: compiler.err.proc.messager: syntax error in reference
CrashInAnnotateTest.java:28:5: compiler.warn.proc.messager: no comment
CrashInAnnotateTest.java:29:16: compiler.warn.proc.messager: no comment
6 errors
3 warnings
6 errors
@@ -17,5 +17,6 @@
* @unknownTag Text for an unknown tag.
*/
public class CustomTagTest {
/** */ CustomTagTest() { }
}

@@ -4,8 +4,8 @@
* @summary Validate parameter names uniqueness
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:-reference DuplicateParamTest.java
* @run main DocLintTester -ref DuplicateParamTest.out DuplicateParamTest.java
* @run main DocLintTester -Xmsgs:all,-missing,-reference DuplicateParamTest.java
* @run main DocLintTester -Xmsgs:all,-missing -ref DuplicateParamTest.out DuplicateParamTest.java
*/

/** . */
@@ -4,8 +4,8 @@
* @summary Validate return uniqueness
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:-reference DuplicateReturnTest.java
* @run main DocLintTester -ref DuplicateReturnTest.out DuplicateReturnTest.java
* @run main DocLintTester -Xmsgs:all,-missing,-reference DuplicateReturnTest.java
* @run main DocLintTester -Xmsgs:all,-missing -ref DuplicateReturnTest.out DuplicateReturnTest.java
*/

/** . */
@@ -10,4 +10,5 @@

/** @author */
public class EmptyAuthorTest {
/** */ EmptyAuthorTest() { }
}
@@ -9,7 +9,7 @@
*/

/** . */
public class EmptyExceptionTest {
public class EmptyExceptionTest { /** */ EmptyExceptionTest() { }
/** @exception NullPointerException */
void emptyException() throws NullPointerException { }
}
@@ -9,7 +9,7 @@
*/

/** . */
public class EmptyParamTest {
public class EmptyParamTest { /** . */ EmptyParamTest() { }
/** @param i */
void emptyParam(int i) { }
}
@@ -9,7 +9,7 @@
*/

/** . */
public class EmptyReturnTest {
public class EmptyReturnTest { /** . */ EmptyReturnTest() { }
/** @return */
int emptyReturn() { return 0; }
}
@@ -12,7 +12,7 @@
import java.io.Serializable;

/** . */
public class EmptySerialDataTest implements Serializable {
public class EmptySerialDataTest implements Serializable { /** . */ EmptySerialDataTest() { }
/**
* .
* @serialData
@@ -12,7 +12,7 @@
import java.io.Serializable;

/** . */
public class EmptySerialFieldTest implements Serializable {
public class EmptySerialFieldTest implements Serializable { /** . */ EmptySerialFieldTest() { }

/**
* @serialField empty String
@@ -9,7 +9,7 @@
*/

/** . */
public class EmptySinceTest {
public class EmptySinceTest { /** . */ EmptySinceTest() { }
/** @since */
void emptySince() { }
}
@@ -9,7 +9,7 @@
*/

/** . */
public class EmptyTagsTest {
public class EmptyTagsTest { /** . */ EmptyTagsTest() { }
/**
* Comment. <p>
*/
@@ -9,7 +9,7 @@
*/

/** . */
public class EmptyVersionTest {
public class EmptyVersionTest { /** . */ EmptyVersionTest() { }
/** @version */
void missingVersion() { }
}
@@ -4,8 +4,8 @@
* @summary doclint: structural issue hidden
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:-html EndTagsTest.java
* @run main DocLintTester -ref EndTagsTest.out EndTagsTest.java
* @run main DocLintTester -Xmsgs:all,-missing,-html EndTagsTest.java
* @run main DocLintTester -Xmsgs:all,-missing -ref EndTagsTest.out EndTagsTest.java
*/

/** */
@@ -29,5 +29,8 @@ private void tagEnd() {}

/**<a name*/
private void attribute() {}

/** . */
EndWithIdentifierTest() { }
}

@@ -4,8 +4,8 @@
* @summary Add new doclint package
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:-html HtmlAttrsTest.java
* @run main DocLintTester -ref HtmlAttrsTest.out HtmlAttrsTest.java
* @run main DocLintTester -Xmsgs:all,-missing,-html HtmlAttrsTest.java
* @run main DocLintTester -Xmsgs:all,-missing -ref HtmlAttrsTest.out HtmlAttrsTest.java
*/

/** */
@@ -4,8 +4,8 @@
* @summary Add new doclint package
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:-html HtmlTagsTest.java
* @run main DocLintTester -ref HtmlTagsTest.out HtmlTagsTest.java
* @run main DocLintTester -Xmsgs:all,-missing,-html HtmlTagsTest.java
* @run main DocLintTester -Xmsgs:all,-missing -ref HtmlTagsTest.out HtmlTagsTest.java
*/

/** */
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.