Repository navigation
Unused Javadoc tag with annotation @return #2141
Description
As discussed in SourceForge Bug 543 and on the Google groups the following code:
@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface SomeAnnotation {
/**
* Some description.
* @return something
*/
String value() default "";
}Will fail with the message:
Unused Javadoc tag
Despite an explicit test for this, I believe that the assumption is wrong and @return tags can (and should) be used with annotation types.
Activity
Issue checkstyle#2141: Allow @return tags from annotation types
romani commentedon Sep 8, 2015
Examples where return tag is not used:
http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/6-b14/java/lang/SuppressWarnings.java
https://github.com/typetools/checker-framework/blob/master/checker/src/org/checkerframework/checker/tainting/qual/Tainted.java
https://github.com/spring-projects/spring-framework/blob/master/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java
Non precise description http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return , still unanswered either Annotation have methods or fields.
Please prove that return tag in annotation is wide-used.
romani commentedon Sep 8, 2015
found one example http://grepcode.com/file_/repository.grepcode.com/java/root/jdk/openjdk/8-b132/java/lang/annotation/Repeatable.java/?v=source
but wee need to find more to get to know why it was not used and why it is started to use, we might need to ask community on stackoverflow.
Look like jdk started to do that from java8 http://grepcode.com/file_/repository.grepcode.com/java/root/jdk/openjdk/8u40-b25/java/lang/SuppressWarnings.java/?v=source (at java6 there was no return tag)
Confirmed: all other annotations of jdk got return tag in java8 and jdk9.
philwebb commentedon Sep 8, 2015
See androidannotations/androidannotations#1198 (comment) for some discussion on the subject. Java 8 tightened the JavaDoc compiler to actually fail if
@returntags are missing.The
@SupressWarningsexample that you gave has been updated in Java 8 to include@Returntags. See http://hg.openjdk.java.net/jdk8/jdk8/jdk/file/687fd7c7986d/src/share/classes/java/lang/SuppressWarnings.java#l69mcandre commentedon Mar 29, 2016
What's the current state of checkstyle re: @return docs for annotations? Does checkstyle now allow for these? Which checkstyle version has the fix?
romani commentedon Apr 1, 2016
checkstyle should allow
@returntag (no violation).problems was fixed at f7698ed
(look at tags "... checkstyle-6.11")
Github Milestone is 6.11, so it is released as 6.11 - http://checkstyle.sourceforge.net/releasenotes.html#Release_6.11.
6.11 had 2 bug fixes so please use - 6.11.2 or latest 6.17.
if smth does not work - please report an issue with all details.