Skip to content

Commit 3ae9f59

Browse files
benzonicoWohops
benzonico
authored and
Wohops
committed
SONARJAVA-1181 Report issue on empty javadoc comments
1 parent 4356815 commit 3ae9f59

4 files changed

Lines changed: 63 additions & 23 deletions

File tree

‎its/ruling/src/test/resources/expected/squid-UndocumentedApi.json‎

Lines changed: 43 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6560,11 +6560,9 @@
65606560
40,
65616561
45,
65626562
56,
6563-
56,
65646563
73,
65656564
79,
65666565
86,
6567-
86,
65686566
104,
65696567
],
65706568
'project:com/sun/corba/se/impl/orbutil/graph/Node.java':[
@@ -10160,6 +10158,7 @@
1016010158
240,
1016110159
246,
1016210160
269,
10161+
278,
1016310162
323,
1016410163
345,
1016510164
349,
@@ -14591,7 +14590,6 @@
1459114590
'project:com/sun/org/apache/xalan/internal/xsltc/compiler/LangCall.java':[
1459214591
50,
1459314592
58,
14594-
58,
1459514593
77,
1459614594
],
1459714595
'project:com/sun/org/apache/xalan/internal/xsltc/compiler/LastCall.java':[
@@ -15964,7 +15962,6 @@
1596415962
90,
1596515963
98,
1596615964
150,
15967-
150,
1596815965
208,
1596915966
208,
1597015967
247,
@@ -17325,6 +17322,9 @@
1732517322
'project:com/sun/org/apache/xerces/internal/impl/dtd/XML11DTDValidator.java':[
1732617323
97,
1732717324
],
17325+
'project:com/sun/org/apache/xerces/internal/impl/dtd/XMLAttributeDecl.java':[
17326+
69,
17327+
],
1732817328
'project:com/sun/org/apache/xerces/internal/impl/dtd/XMLContentSpec.java':[
1732917329
220,
1733017330
227,
@@ -17362,9 +17362,19 @@
1736217362
1087,
1736317363
2064,
1736417364
],
17365+
'project:com/sun/org/apache/xerces/internal/impl/dtd/XMLElementDecl.java':[
17366+
69,
17367+
],
17368+
'project:com/sun/org/apache/xerces/internal/impl/dtd/XMLEntityDecl.java':[
17369+
66,
17370+
],
1736517371
'project:com/sun/org/apache/xerces/internal/impl/dtd/XMLNotationDecl.java':[
17372+
66,
1736617373
95,
1736717374
],
17375+
'project:com/sun/org/apache/xerces/internal/impl/dtd/XMLSimpleType.java':[
17376+
68,
17377+
],
1736817378
'project:com/sun/org/apache/xerces/internal/impl/dtd/models/CMAny.java':[
1736917379
106,
1737017380
149,
@@ -17396,6 +17406,9 @@
1739617406
'project:com/sun/org/apache/xerces/internal/impl/dtd/models/CMUniOp.java':[
1739717407
77,
1739817408
],
17409+
'project:com/sun/org/apache/xerces/internal/impl/dtd/models/ContentModelValidator.java':[
17410+
68,
17411+
],
1739917412
'project:com/sun/org/apache/xerces/internal/impl/dv/DVFactoryException.java':[
1740017413
35,
1740117414
39,
@@ -17736,7 +17749,6 @@
1773617749
1029,
1773717750
1316,
1773817751
1326,
17739-
1326,
1774017752
2003,
1774117753
],
1774217754
'project:com/sun/org/apache/xerces/internal/impl/xpath/XPathException.java':[
@@ -17774,7 +17786,6 @@
1777417786
299,
1777517787
299,
1777617788
308,
17777-
308,
1777817789
],
1777917790
'project:com/sun/org/apache/xerces/internal/impl/xpath/regex/RangeToken.java':[
1778017791
543,
@@ -18398,6 +18409,9 @@
1839818409
580,
1839918410
586,
1840018411
],
18412+
'project:com/sun/org/apache/xerces/internal/impl/xs/opti/SchemaParsingConfig.java':[
18413+
1010,
18414+
],
1840118415
'project:com/sun/org/apache/xerces/internal/impl/xs/opti/TextImpl.java':[
1840218416
40,
1840318417
],
@@ -19032,6 +19046,7 @@
1903219046
423,
1903319047
],
1903419048
'project:com/sun/org/apache/xerces/internal/parsers/DTDParser.java':[
19049+
37,
1903519050
123,
1903619051
134,
1903719052
153,
@@ -19084,6 +19099,9 @@
1908419099
181,
1908519100
189,
1908619101
],
19102+
'project:com/sun/org/apache/xerces/internal/parsers/XMLGrammarParser.java':[
19103+
30,
19104+
],
1908719105
'project:com/sun/org/apache/xerces/internal/parsers/XMLGrammarPreparser.java':[
1908819106
152,
1908919107
273,
@@ -19555,12 +19573,14 @@
1955519573
206,
1955619574
],
1955719575
'project:com/sun/org/apache/xerces/internal/util/XMLStringBuffer.java':[
19576+
108,
1955819577
122,
1955919578
128,
1956019579
134,
1956119580
140,
1956219581
],
1956319582
'project:com/sun/org/apache/xerces/internal/xinclude/MultipleScopeNamespaceSupport.java':[
19583+
49,
1956419584
94,
1956519585
105,
1956619586
112,
@@ -19626,6 +19646,9 @@
1962619646
2688,
1962719647
2744,
1962819648
],
19649+
'project:com/sun/org/apache/xerces/internal/xinclude/XIncludeNamespaceSupport.java':[
19650+
43,
19651+
],
1962919652
'project:com/sun/org/apache/xerces/internal/xinclude/XPointerElementHandler.java':[
1963019653
180,
1963119654
194,
@@ -19819,6 +19842,7 @@
1981919842
81,
1982019843
],
1982119844
'project:com/sun/org/apache/xerces/internal/xpointer/XPointerHandler.java':[
19845+
102,
1982219846
109,
1982319847
129,
1982419848
286,
@@ -20447,6 +20471,8 @@
2044720471
210,
2044820472
],
2044920473
'project:com/sun/org/apache/xml/internal/security/c14n/implementations/Canonicalizer20010315ExclOmitComments.java':[
20474+
30,
20475+
36,
2045020476
41,
2045120477
46,
2045220478
],
@@ -20482,8 +20508,10 @@
2048220508
2815,
2048320509
3529,
2048420510
3533,
20511+
3590,
2048520512
3606,
2048620513
3610,
20514+
3657,
2048720515
3694,
2048820516
3694,
2048920517
3698,
@@ -20501,6 +20529,10 @@
2050120529
3949,
2050220530
3959,
2050320531
],
20532+
'project:com/sun/org/apache/xml/internal/security/encryption/XMLEncryptionException.java':[
20533+
28,
20534+
37,
20535+
],
2050420536
'project:com/sun/org/apache/xml/internal/security/exceptions/XMLSecurityException.java':[
2050520537
179,
2050620538
],
@@ -20637,6 +20669,9 @@
2063720669
'project:com/sun/org/apache/xml/internal/security/utils/ElementProxy.java':[
2063820670
539,
2063920671
],
20672+
'project:com/sun/org/apache/xml/internal/security/utils/HelperNodeList.java':[
20673+
43,
20674+
],
2064020675
'project:com/sun/org/apache/xml/internal/security/utils/IdResolver.java':[
2064120676
237,
2064220677
],
@@ -23119,7 +23154,6 @@
2311923154
794,
2312023155
798,
2312123156
819,
23122-
819,
2312323157
884,
2312423158
914,
2312523159
931,
@@ -23131,7 +23165,6 @@
2313123165
300,
2313223166
301,
2313323167
379,
23134-
379,
2313523168
483,
2313623169
585,
2313723170
585,
@@ -23571,7 +23604,6 @@
2357123604
127,
2357223605
131,
2357323606
175,
23574-
175,
2357523607
195,
2357623608
208,
2357723609
213,
@@ -27243,6 +27275,7 @@
2724327275
411,
2724427276
],
2724527277
'project:javax/management/modelmbean/RequiredModelMBean.java':[
27278+
160,
2724627279
2149,
2724727280
2181,
2724827281
2255,
@@ -27251,7 +27284,6 @@
2725127284
2557,
2725227285
2681,
2725327286
2795,
27254-
2795,
2725527287
],
2725627288
'project:javax/management/monitor/CounterMonitor.java':[
2725727289
89,
@@ -33242,6 +33274,7 @@
3324233274
],
3324333275
'project:javax/swing/undo/UndoableEditSupport.java':[
3324433276
114,
33277+
135,
3324533278
],
3324633279
'project:javax/tools/DiagnosticCollector.java':[
3324733280
45,
@@ -34298,10 +34331,8 @@
3429834331
],
3429934332
'project:org/omg/CORBA_2_3/ORB.java':[
3430034333
43,
34301-
43,
3430234334
53,
3430334335
62,
34304-
62,
3430534336
74,
3430634337
74,
3430734338
84,

‎java-checks/src/main/java/org/sonar/java/checks/UndocumentedApiCheck.java‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
import com.google.common.base.Joiner;
2323
import com.google.common.collect.ImmutableList;
2424
import com.google.common.collect.Lists;
25+
import org.apache.commons.lang.StringUtils;
2526
import org.sonar.api.server.rule.RulesDefinition;
2627
import org.sonar.api.utils.WildcardPattern;
2728
import org.sonar.check.Priority;
@@ -125,7 +126,7 @@ public void visitMethod(MethodTree tree) {
125126
private void visitNode(Tree tree) {
126127
if (!isExcluded(tree)) {
127128
String javadoc = PublicApiChecker.getApiJavadoc(tree);
128-
if (javadoc == null) {
129+
if (javadoc == null || isEmptyJavadoc(javadoc)) {
129130
context.addIssue(tree, this, "Document this public " + getType(tree) + ".");
130131
} else if (!javadoc.contains("{@inheritDoc}")) {
131132
List<String> undocumentedParameters = getUndocumentedParameters(javadoc, getParameters(tree));
@@ -139,6 +140,12 @@ private void visitNode(Tree tree) {
139140
}
140141
}
141142

143+
private static boolean isEmptyJavadoc(String javadoc) {
144+
//remove start and end of doc as well as stars.
145+
String cleanedupJavadoc = javadoc.trim().substring(3).replace("*/", "").replace("*", "").trim();
146+
return StringUtils.isBlank(cleanedupJavadoc);
147+
}
148+
142149
private static String getType(Tree tree) {
143150
String result = "";
144151
if (tree.is(Tree.Kind.CLASS)) {

‎java-checks/src/test/files/checks/UndocumentedApi.java‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -102,8 +102,8 @@ public int doSomething(int value) { // Non-Compliant - missing '@para
102102
return value;
103103
}
104104

105-
/**
106-
*/
105+
/** plop
106+
* */
107107
public int doSomething() { // Non-Compliant - missing '@return'
108108
return value;
109109
}
@@ -113,19 +113,19 @@ public int doSomething() { // Non-Compliant - missing '@retu
113113
*/
114114
interface FooInterface {
115115
/**
116-
*/
116+
* void. */
117117
void foo(); // Compliant
118118

119119
/**
120-
*/
120+
* bar. */
121121
int foo(); // Non-Compliant
122122

123123
/**
124124
* @return
125125
*/
126126
int foo(); // Compliant
127127

128-
/**
128+
/** plop.
129129
*/
130130
void foo(int a); // Non-Compliant
131131
}
@@ -134,7 +134,7 @@ interface FooInterface {
134134
*
135135
*/
136136
class FooClass {
137-
/**
137+
/** constructor.
138138
*/
139139
public FooClass(int a) { // Non-Compliant
140140
System.out.println(a);
@@ -154,10 +154,10 @@ private class FooPrivate { // Compliant - non pubic
154154
class FooPackage { // Compliant - non public
155155
}
156156

157-
/**
157+
/** Documented.
158158
*/
159159
public class Foo { // Compliant
160-
/**
160+
/** foo.
161161
*/
162162
public int foo(int a, int b, int c) { // Non-Compliant - single issue for parameters, + one for return value
163163
return 0;
@@ -195,7 +195,7 @@ public void getThisThingDone() { //false negative this is interpreted as a gette
195195
}
196196
/**
197197
* */
198-
public interface bar {
198+
public interface bar { // Noncompliant empty documentation
199199
/**
200200
* @param <A> the annotation type
201201
* @param annotationType the <tt>Class</tt> object corresponding to
@@ -264,7 +264,7 @@ private interface Bar {
264264
{
265265
}
266266

267-
/**
267+
/** Foo.
268268
*/
269269
public interface Foo {
270270

‎java-checks/src/test/java/org/sonar/java/checks/UndocumentedApiCheckTest.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,9 @@ public void test() {
6464
.next().atLine(167).withMessage("Document this public method.")
6565
.next().atLine(177).withMessage("Document this public method.")
6666
.next().atLine(183).withMessage("Document this method return value.")
67+
.next().atLine(198).withMessage("Document this public interface.")
6768
.next().atLine(208).withMessage("Document this public class.")
69+
.next().atLine(223).withMessage("Document this public class.")
6870
.next().atLine(262)
6971
.next().atLine(271)
7072
.next().atLine(277)

0 commit comments

Comments
 (0)