Skip to content
Permalink
Browse files
8249634: doclint should report implicit constructor as missing javado…
…c comments

Reviewed-by: hannesw
  • Loading branch information
jonathan-gibbons committed Jul 22, 2021
1 parent 09e5321 commit c1c404896ca2791ad348a4cf482beb2c2ad98464
Showing 76 changed files with 231 additions and 114 deletions.
@@ -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.
* 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
@@ -27,7 +27,7 @@
* @summary ignore declarations in lambda expressions
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:all SyntheticTest.java
* @run main DocLintTester -Xmsgs:all LambdaTest.java
*/

package acme;
@@ -41,6 +41,8 @@
*/
public final class LambdaTest
{
/** */ LambdaTest() { }

/**
* The field itself has docs.
*/

1 comment on commit c1c4048

@openjdk-notifier
Copy link

@openjdk-notifier openjdk-notifier bot commented on c1c4048 Jul 22, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.