Permalink
Browse files

Issue #3908: SummaryJavadoc need special processing of inheritDoc tag

  • Loading branch information...
sagarshah94 committed Mar 18, 2017
1 parent 1b5a154 commit 1ebbca161e57c41d30671ee3e340b32369ab2007
@@ -19,6 +19,9 @@
package com.puppycrawl.tools.checkstyle.checks.javadoc;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
import java.util.regex.Pattern;
import com.google.common.base.CharMatcher;
@@ -82,6 +85,14 @@
/** Period literal. */
private static final String PERIOD = ".";
/**
* Stores allowed values in document for inherit doc literal.
*/
private static final Set<Integer> SKIP_TOKENS = new HashSet<>(
Arrays.asList(JavadocTokenTypes.NEWLINE,
JavadocTokenTypes.LEADING_ASTERISK,
JavadocTokenTypes.EOF)
);
/**
* Regular expression for forbidden summary fragments.
*/
@@ -135,7 +146,7 @@ public void visitJavadocToken(DetailNode ast) {
String firstSentence = getFirstSentence(ast);
final int endOfSentence = firstSentence.lastIndexOf(period);
if (endOfSentence == -1) {
if (!firstSentence.trim().startsWith("{@inheritDoc}")) {
if (!isOnlyInheritDoc(ast)) {
log(ast.getLineNumber(), MSG_SUMMARY_FIRST_SENTENCE);
}
}
@@ -147,6 +158,38 @@ public void visitJavadocToken(DetailNode ast) {
}
}
/**
* Finds if inheritDoc is placed properly in java doc.
* @param ast Javadoc root node.
* @return true if inheritDoc is valid or false.
*/
private static boolean isOnlyInheritDoc(DetailNode ast) {
boolean extraTextFound = false;
boolean containsInheritDoc = false;
for (DetailNode child : ast.getChildren()) {
if (child.getType() == JavadocTokenTypes.TEXT) {
if (!child.getText().trim().isEmpty()) {
extraTextFound = true;
}
}
else if (child.getType() == JavadocTokenTypes.JAVADOC_INLINE_TAG) {
if (child.getChildren()[1].getType() == JavadocTokenTypes.INHERIT_DOC_LITERAL) {
containsInheritDoc = true;
}
else {
extraTextFound = true;
}
}
else if (!SKIP_TOKENS.contains(child.getType())) {
extraTextFound = true;
}
if (extraTextFound) {
break;
}
}
return containsInheritDoc && !extraTextFound;
}
/**
* Finds and returns first sentence.
* @param ast Javadoc root node.
@@ -76,6 +76,10 @@ public void testIncorrect() throws Exception {
"69: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"83: " + getCheckMessage(MSG_SUMMARY_JAVADOC),
"103: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"116: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"121: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"126: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"131: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
};
verify(checkConfig, getPath("InputIncorrectSummaryJavaDoc.java"), expected);
}
@@ -106,6 +110,10 @@ public void testDefaultConfiguration() throws Exception {
"37: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"69: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"103: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"116: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"121: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"126: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
"131: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
};
createChecker(checkConfig);
@@ -32,6 +32,22 @@ void foo6() {}
/** {@inheritDoc} */
void foo7() {}
/**
* {@inheritDoc} */
void foo8() {}
/**
* {@inheritDoc}
*/
void foo9() {}
/**
*
*
* {@inheritDoc}
*/
void foo10() {}
/**
* <a href="mailto:vlad@htmlbook.ru"/>
*/
@@ -112,5 +112,25 @@ void foo5() {}
* An especially short bit of Javadoc.
*/
void foo6() {}
/**
* mm{@inheritDoc}
*/
void foo7() {}
/**
* {@inheritDoc}mm
*/
void foo9() {}
/**
* {@link #setBounds(int,int,int,int)}
*/
void foo8() {}
/**
*
*/
void foo10() {}
};
}
@@ -1581,7 +1581,8 @@ public boolean isSomething()
<subsection name="Description">
<p>
Checks that <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#firstsentence">
Javadoc summary sentence</a> does not contain phrases that are not recommended to use.
Javadoc summary sentence</a> does not contain phrases that are not recommended to use. Comments that contains
only InheritDoc tag are skipped.
</p>
</subsection>
@@ -1630,6 +1631,21 @@ public boolean isSomething()
&lt;module name=&quot;SummaryJavadocCheck&quot;&gt;
&lt;property name=&quot;period&quot; value="。"/&gt;
&lt;/module&gt;
</source>
<p>
Example of {@inheritDoc} without summary.
</p>
<source>
<![CDATA[
public class Test extends Exception {
/**
* {@inheritDoc}
*/
public String toString(){
return "";
}
}
]]>
</source>
<p>
Example of period property.

0 comments on commit 1ebbca1

Please sign in to comment.