Check since tags on nested elements

Closes gh-462

Author: wilkinsona

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

@@ -81,7 +81,7 @@ public class SpringJavadocCheck extends AbstractSpringCheck {
 	@Override
 	public int[] getDefaultTokens() {
 		return new int[] { TokenTypes.INTERFACE_DEF, TokenTypes.CLASS_DEF, TokenTypes.ENUM_DEF,
-				TokenTypes.ANNOTATION_DEF, TokenTypes.METHOD_DEF, TokenTypes.CTOR_DEF };
+				TokenTypes.ANNOTATION_DEF, TokenTypes.METHOD_DEF, TokenTypes.CTOR_DEF, TokenTypes.ANNOTATION_FIELD_DEF };
 	}
 
 	@Override
@@ -130,6 +130,7 @@ private void checkJavadoc(DetailAST ast, TextBlock javadoc) {
 		checkTagCase(ast, javadoc);
 		checkSinceTag(ast, javadoc);
 		checkMethodJavaDoc(ast, javadoc);
+		checkAnnotationFieldJavaDoc(ast, javadoc);
 	}
 
 	private void checkBannedTags(DetailAST ast, TextBlock javadoc) {
@@ -164,25 +165,54 @@ private void checkSinceTag(DetailAST ast, TextBlock javadoc) {
 		if (!TOP_LEVEL_TYPES.contains(ast.getType())) {
 			return;
 		}
-		String[] text = javadoc.getText();
 		DetailAST interfaceOrAnnotationDef = getInterfaceOrAnnotationDef(ast);
 		boolean privateType = !isPublicOrProtected(ast)
 				&& (interfaceOrAnnotationDef == null || !isPublicOrProtected(interfaceOrAnnotationDef));
-		boolean innerType = ast.getParent() != null && ast.getParent().getType() != TokenTypes.COMPILATION_UNIT;
-		boolean found = false;
-		for (int i = 0; i < text.length; i++) {
-			Matcher matcher = SINCE_TAG_PATTERN.matcher(text[i]);
-			if (matcher.find()) {
-				found = true;
-				String description = matcher.group(1).trim();
-				if (this.publicOnlySinceTags && privateType) {
-					log(javadoc.getStartLineNo() + i, text[i].length() - description.length(), "javadoc.publicSince");
-				}
+		SinceTag sinceTag = SinceTag.find(ast, javadoc);
+		if (sinceTag != null) {
+			if (this.publicOnlySinceTags && privateType) {
+				log(sinceTag.lineNumber, sinceTag.columnNumber, "javadoc.publicSince");
+			}
+			else {
+				checkContainingSince(ast, sinceTag);
 			}
 		}
-		if (this.requireSinceTag && !innerType && !found && !(this.publicOnlySinceTags && privateType)) {
-			log(javadoc.getStartLineNo(), 0, "javadoc.missingSince");
+		else {
+			boolean innerType = ast.getParent() != null && ast.getParent().getType() != TokenTypes.COMPILATION_UNIT;
+			if (this.requireSinceTag && !innerType && sinceTag == null && !(this.publicOnlySinceTags && privateType)) {
+				log(javadoc.getStartLineNo(), 0, "javadoc.missingSince");
+			}
+		}
+	}
+
+	private void checkContainingSince(DetailAST ast, SinceTag currentTag) {
+		SinceTag containingSince = findContainingSince(ast);
+		if (containingSince != null) {
+			SinceVersion current = currentTag.version;
+			SinceVersion container = containingSince.version;
+			int comparison = current.compareTo(container);
+			if (comparison < 0) {
+				log(currentTag.lineNumber, currentTag.columnNumber, "javadoc.earlierSince", current, container, containingSince.lineNumber, containingSince.columnNumber);
+			}
+			else if (comparison == 0) {
+				log(currentTag.lineNumber, currentTag.columnNumber, "javadoc.sameSince", current, containingSince.lineNumber, containingSince.columnNumber);
+			}
+		}
+	}
+
+	private SinceTag findContainingSince(DetailAST ast) {
+		DetailAST parent = ast.getParent();
+		while (parent != null && parent.getType() != TokenTypes.COMPILATION_UNIT) {
+			TextBlock javadoc = getFileContents().getJavadocBefore(parent.getLineNo());
+			if (javadoc != null) {
+				SinceTag sinceTag = SinceTag.find(ast, javadoc);
+				if (sinceTag != null) {
+					return sinceTag;
+				}
+			}
+			parent = parent.getParent();
 		}
+		return null;
 	}
 
 	private void checkMethodJavaDoc(DetailAST ast, TextBlock javadoc) {
@@ -196,6 +226,20 @@ private void checkMethodJavaDoc(DetailAST ast, TextBlock javadoc) {
 				log(javadoc.getStartLineNo() + i - 1, 0, "javadoc.emptyLineBeforeTag");
 			}
 		}
+		SinceTag sinceTag = SinceTag.find(ast, javadoc);
+		if (sinceTag != null) {
+			checkContainingSince(ast, sinceTag);
+		}
+	}
+
+	private void checkAnnotationFieldJavaDoc(DetailAST ast, TextBlock javadoc) {
+		if (TokenTypes.ANNOTATION_FIELD_DEF != ast.getType()) {
+			return;
+		}
+		SinceTag sinceTag = SinceTag.find(ast, javadoc);
+		if (sinceTag != null) {
+			checkContainingSince(ast, sinceTag);
+		}
 	}
 
 	private boolean startsWithUppercase(String description) {
@@ -251,4 +295,74 @@ private boolean isPublicOrProtected(DetailAST ast) {
 				|| modifiers.findFirstToken(TokenTypes.LITERAL_PROTECTED) != null;
 	}
 
+	private static final class SinceTag {
+
+		private final int lineNumber;
+
+		private final int columnNumber;
+
+		private final SinceVersion version;
+
+		private SinceTag(int lineNumber, int columnNumber, SinceVersion version) {
+			this.lineNumber = lineNumber;
+			this.columnNumber = columnNumber;
+			this.version = version;
+		}
+
+		private static SinceTag find(DetailAST ast, TextBlock javadoc) {
+			String[] text = javadoc.getText();
+			for (int i = 0; i < text.length; i++) {
+				Matcher matcher = SINCE_TAG_PATTERN.matcher(text[i]);
+				if (matcher.find()) {
+					String description = matcher.group(1).trim();
+					return new SinceTag(javadoc.getStartLineNo() + i, text[i].length() - description.length(), SinceVersion.of(description));
+				}
+			}
+			return null;
+		}
+	}
+
+	private static final class SinceVersion implements Comparable<SinceVersion> {
+
+		private final int major;
+
+		private final int minor;
+
+		private final int patch;
+
+		private final String text;
+
+		private SinceVersion(int major, int minor, int patch, String text) {
+			this.major = major;
+			this.minor = minor;
+			this.patch = patch;
+			this.text = text;
+		}
+
+		private static SinceVersion of(String text) {
+			String[] components = text.split("\\.");
+			int major = (components.length > 0) ? Integer.parseInt(components[0]) : 0;
+			int minor = (components.length > 1) ? Integer.parseInt(components[1]) : 0;
+			int patch = (components.length > 2) ? Integer.parseInt(components[2]) : 0;
+			return new SinceVersion(major, minor, patch, text);
+		}
+
+		public String toString() {
+			return this.text;
+		}
+
+		@Override
+		public int compareTo(SinceVersion other) {
+			int diff = this.major - other.major;
+			if (diff == 0) {
+				diff = this.minor - other.minor;
+				if (diff == 0) {
+					diff = this.patch - other.patch;
+				}
+			}
+			return diff;
+		}
+
+	}
+
 }

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

@@ -11,7 +11,9 @@ import.avoidStatic=Using a static member import should be avoided - {0}.
 import.ordering=Wrong order for ''{0}'' import.
 javadoc.badCase=Javadoc element descriptions should not start with an uppercase letter.
 javadoc.bannedTag=Javadoc tag ''{0}'' should not be used.
+javadoc.earlierSince=Javadoc @since version ''{0}'' is earlier than @since version ''{1}'' at {2}:{3}.
 javadoc.missingSince=Missing Javadoc @since tag.
+javadoc.sameSince=Javadoc @since version ''{0}'' is unnecessary as it is the same as the @since version at {1}:{2}.
 javadoc.publicSince=Javadoc @since tag should not be used on private classes.
 javadoc.emptyLineBeforeTag=Method Javadoc should not have empty line before tag.
 javadoc.nonJavadocComment=Comments should not include \"(non-Javadoc)\".

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

@@ -0,0 +1,2 @@
++28:19: Javadoc @since version '1.1.0' is earlier than @since version '1.2.0' at 21:10. 
++1 error

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

@@ -0,0 +1,2 @@
++28:19: Javadoc @since version '1.2.3' is earlier than @since version '2.0.0' at 21:10. 
++1 error

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

@@ -0,0 +1,2 @@
++27:19: Javadoc @since version '1.2.3' is earlier than @since version '2.0.0' at 21:10. 
++1 error

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

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2017-present 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 good since tag.
+ *
+ * @author Andy Wilkinson
+ * @since 1.2.0
+ */
+public @interface JavadocAnnotationFieldHasEarlierSince {
+
+	/**
+	 * An attribute.
+	 * @return the value
+	 * @since 1.1.0
+	 */
+	boolean attribute() default true;
+
+}

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

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2017-present 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 an earlier since tag on an inner class.
+ *
+ * @author Phillip Webb
+ * @since 2.0.0
+ */
+class JavadocInnerClassHasEarlierSince {
+
+	/**
+	 * Inner class.
+	 *
+	 * @since 1.2.3
+	 */
+	private static class Inner {
+
+	}
+
+}

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

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2017-present 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 an earlier since tag on a method.
+ *
+ * @author Andy Wilkinson
+ * @since 2.0.0
+ */
+public class JavadocMethodHasEarlierSince {
+
+	/**
+	 * Some method.
+	 * @since 1.2.3
+	 */
+	public void someMethod() {
+
+	}
+
+}

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

@@ -25,7 +25,7 @@ class JavadocNonPublicSince {
 	/**
 	 * Inner class.
 	 *
-	 * @since 1.2.3
+	 * @since 1.2.4
 	 */
 	private static class Inner {
 

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

@@ -25,7 +25,7 @@
 	/**
 	 * Inner enum.
 	 *
-	 * @since 1.2.3
+	 * @since 1.2.4
 	 */
 	enum Inner {