From 847a09d68f29a0551c76db66f2fed9cc3e5a57c5 Mon Sep 17 00:00:00 2001
From: Roman Ivanov <ivanov-jr@mail.ru>
Date: Wed, 18 May 2016 05:48:26 -0700
Subject: [PATCH] Issue #3164: AnnotationLocation: unclear behavior when
 annotation is among modifiers

---
 .../checks/annotation/AnnotationLocationCheck.java         | 7 +++++++
 src/xdocs/config_annotation.xml                            | 6 ++++++
 2 files changed, 13 insertions(+)

diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/AnnotationLocationCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/AnnotationLocationCheck.java
index ea29cea4a..940ccf5a6 100644
--- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/AnnotationLocationCheck.java
+++ b/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:
diff --git a/src/xdocs/config_annotation.xml b/src/xdocs/config_annotation.xml
index 0176a311c..2e1185ff0 100644
--- a/src/xdocs/config_annotation.xml
+++ b/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>