Checkstyle rule for @SInCE on private classes

Update `SpringJavadocCheck` to optionally support checking that `@since`
is not used on private classes.

Closes gh-129

Author: philwebb

spring-javaformat/spring-javaformat-checkstyle/src/main/java/io/spring/javaformat/checkstyle/check/SpringJavadocCheck.java

@@ -30,9 +30,13 @@
  */
 public class SpringJavadocCheck extends AbstractSpringCheck {
 
-	private static final Pattern[] PATTERNS = { Pattern.compile("@param\\s+\\S+\\s+(.*)"),
+	private static final Pattern[] CASE_CHECKED_TAG_PATTERNS = { Pattern.compile("@param\\s+\\S+\\s+(.*)"),
 			Pattern.compile("@throws\\s+\\S+\\s+(.*)"), Pattern.compile("@return\\s+(.*)") };
 
+	private static final Pattern SINCE_TAG_PATTERN = Pattern.compile("@since\\s+(.*)");
+
+	private boolean publicOnlySinceTags;
+
 	@Override
 	public int[] getDefaultTokens() {
 		return new int[] { TokenTypes.INTERFACE_DEF, TokenTypes.CLASS_DEF, TokenTypes.ENUM_DEF,
@@ -51,27 +55,63 @@ public void visitToken(DetailAST ast) {
 		int lineNumber = ast.getLineNo();
 		TextBlock javadoc = getFileContents().getJavadocBefore(lineNumber);
 		if (javadoc != null) {
-			checkParamTags(javadoc);
+			checkParamTags(ast, javadoc);
 		}
 	}
 
-	private void checkParamTags(TextBlock javadoc) {
+	private void checkParamTags(DetailAST ast, TextBlock javadoc) {
 		String[] text = javadoc.getText();
 		for (int i = 0; i < text.length; i++) {
-			for (Pattern pattern : PATTERNS) {
-				Matcher matcher = pattern.matcher(text[i]);
-				if (matcher.find()) {
-					String description = matcher.group(1).trim();
-					if (startsWithUppercase(description)) {
-						log(javadoc.getStartLineNo() + i, text[i].length() - description.length(), "javadoc.badCase");
-					}
+			String line = text[i];
+			int lineNumber = javadoc.getStartLineNo() + i;
+			checkCase(line, lineNumber);
+			checkSinceTag(ast, line, lineNumber);
+		}
+	}
+
+	private void checkCase(String line, int lineNumber) {
+		for (Pattern pattern : CASE_CHECKED_TAG_PATTERNS) {
+			Matcher matcher = pattern.matcher(line);
+			if (matcher.find()) {
+				String description = matcher.group(1).trim();
+				if (startsWithUppercase(description)) {
+					log(lineNumber, line.length() - description.length(), "javadoc.badCase");
+				}
+			}
+		}
+	}
+
+	private void checkSinceTag(DetailAST ast, String line, int lineNumber) {
+		if (this.publicOnlySinceTags) {
+			Matcher matcher = SINCE_TAG_PATTERN.matcher(line);
+			if (matcher.find()) {
+				String description = matcher.group(1).trim();
+				DetailAST classDef = getClassDef(ast);
+				DetailAST classModifiers = classDef.findFirstToken(TokenTypes.MODIFIERS);
+				if (classModifiers.findFirstToken(TokenTypes.LITERAL_PUBLIC) == null
+						&& classModifiers.findFirstToken(TokenTypes.LITERAL_PROTECTED) == null) {
+					log(lineNumber, line.length() - description.length(), "javadoc.publicSince");
 				}
 			}
 		}
 	}
 
+	private DetailAST getClassDef(DetailAST ast) {
+		while (ast != null) {
+			if (ast.getType() == TokenTypes.CLASS_DEF) {
+				return ast;
+			}
+			ast = ast.getParent();
+		}
+		return null;
+	}
+
 	private boolean startsWithUppercase(String description) {
 		return description.length() > 0 && Character.isUpperCase(description.charAt(0));
 	}
 
+	public void setPublicOnlySinceTags(boolean publicOnlySinceTags) {
+		this.publicOnlySinceTags = publicOnlySinceTags;
+	}
+
 }

spring-javaformat/spring-javaformat-checkstyle/src/main/resources/io/spring/javaformat/checkstyle/check/messages.properties

@@ -5,6 +5,7 @@ ternary.missingParen=Ternary operation missing parentheses.
 ternary.equalOperator=Ternary operation should use != when testing.
 catch.singleLetter=Single letter catch variable (use "ex" instead).
 javadoc.badCase=Javadoc element descriptions should not start with an uppercase letter.
+javadoc.publicSince=Javadoc @since tag should not be used on private classes.
 header.unexpected=Unexpected header.
 nothis.unexpected=Reference to instance variable ''{0}'' should not use \"this.\".
 methodorder.outOfOrder=Method ''{0}'' is out of order, expected {1}.

spring-javaformat/spring-javaformat-checkstyle/src/test/resources/check/JavadocNonPublicSince.txt

@@ -0,0 +1,3 @@
++JavadocNonPublicSince.java:21:11: Javadoc @since tag should not be used on private classes. [SpringJavadoc]
++JavadocNonPublicSince.java:28:19: Javadoc @since tag should not be used on private classes. [SpringJavadoc]
++2 errors

spring-javaformat/spring-javaformat-checkstyle/src/test/resources/config/JavadocNonPublicSince.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+		"-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+		"https://checkstyle.org/dtds/configuration_1_3.dtd">
+<module name="com.puppycrawl.tools.checkstyle.Checker">
+	<module name="com.puppycrawl.tools.checkstyle.TreeWalker">
+		<module name="io.spring.javaformat.checkstyle.check.SpringJavadocCheck">
+			<property name="publicOnlySinceTags" value="true"/>
+		</module>
+	</module>
+</module>

spring-javaformat/spring-javaformat-checkstyle/src/test/resources/source/JavadocNonPublicSince.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2017-2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Javadoc with a bad since tag.
+ *
+ * @author Phillip Webb
+ * @since 1.2.3
+ */
+class JavadocNonPublicSince {
+
+	/**
+	 * Inner class.
+	 *
+	 * @since 1.2.3
+	 */
+	private static class Inner {
+
+	}
+
+}

spring-javaformat/spring-javaformat-checkstyle/src/test/resources/source/JavadocValid.java

@@ -15,7 +15,7 @@
  */
 
 /**
- * Javadoc with a bad author tag.
+ * Valid Javadoc.
  *
  * @param <T> this is a valid param
  * @author Phillip Webb