Issue #3164: AnnotationLocation: unclear behavior when annotation is among modifiers

src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/AnnotationLocationCheck.java

@@ -29,6 +29,13 @@ import com.puppycrawl.tools.checkstyle.utils.CommonUtils;
  * By default, Check enforce to locate annotations immediately after
  * documentation block and before target element, annotation should be located
  * on separate line from target element.
+ * <p>
+ * Attention: Annotations among modifiers are ignored (looks like false-negative)
+ * as there might be a problem with annotations for return types
+ * <pre>public @Nullable Long getStartTimeOrNull() { ... }</pre>.
+ * Such annotations are better to keep close to type.
+ * Due to limitations Checkstyle can not examin target of annotation.
+ * </p>
  *
  * <p>
  * Example:

src/xdocs/config_annotation.xml

@@ -28,6 +28,12 @@
           By default, Check enforce to locate annotations immediately
           after documentation block and before target element, annotation should be located on separate line from target element.
         </p>
+        <p>
+          Attention: Annotations among modifiers are ignored (looks like false-negative)
+          as there might be a problem with annotations for return types <source>public @Nullable Long getStartTimeOrNull() { ... }</source>
+          Such annotations are better to keep close to type.
+          Due to limitations Checkstyle can not examin target of annotation.
+        </p>
         <p>
           Example:
         </p>