39

Since I updated my Android Studio (2.3.1) and build tools (2.3.1), I'm getting warning,

Warning: Dangling Javadoc comment

for comments like,

/** set name with format, {@Link FORMAT_NAME} **/
setNameText(getFormattedName(FORMAT_NAME));

As you can see, I use javadoc style comment for linking and others. I'm wondering if there are other comment alternatives that have linking feature.

Thanks.

Dhunju_likes_to_Learn
  • 1,201
  • 1
  • 16
  • 25
  • comment, you mentioned, should really be regular javadoc comment for that method. This is because, comment describes, what that method is doing, and code comments should describe - why are you calling that method and not other. – Alexander Semenov May 03 '17 at 10:13

6 Answers6

25

It looks like you are using a Javadoc comment when you call the method setNameText. Javadoc comments are to be inserted above a class declaration, a method declaration, or a field declaration.

If you simply want a comment when calling the method, use the one-line comment: // get formatted name based on {@link FORMAT_NAME}.

gjigandi
  • 486
  • 3
  • 7
25

In case it helps someone else, make sure you didn't sneak your JavaDoc between the method/class definition and any annotations you had on that definition.

Snekse
  • 15,474
  • 10
  • 62
  • 77
  • 2
    The IDE ought to provide this as an auto-fix option. Or detect it as a distinct error like "javadoc between attribute and declaration" – Keith Tyler Jan 17 '23 at 00:48
20

You are using Javadoc format which starts with /** instead of a block comment format which starts with /* .

To alleviate that warning, always start your comments inside the methods with /* not /**.

Dev_mjm
  • 391
  • 3
  • 4
2

Just replace "Dangling Javadoc Comment" with block comment.

Cobain
  • 186
  • 1
  • 8
  • 3
    Then you cannot use {@link } - that is indexed by IDEs only in javadocs. – Ev0oD Oct 31 '17 at 14:01
  • 1
    @Ev0oD If u want to use {@link}, maybe the best choice is disable the "Dangling Javadoc comments" report in the AS's Inspections. Then u can use "Javadoc comments" anywhere, but this is not recommended. – Cobain Nov 03 '17 at 03:38
2

You may just turn it off in page "File-Settings-Editor-Inspections-Java-Javadoc issues-Dangling Javadoc comment".

Qian Sijianhao
  • 564
  • 7
  • 19
  • 3
    Warnings are there to help improve the quality of your code, you don't just turn them off. There's a reason behind this warning, as other answers explain. – pedram bashiri Oct 18 '18 at 19:23
  • 2
    The only scenario where you might turn off a warning is when you have convincing reasons that the warning is unnecessary which I don't think is the case here. If you really think this warning is unnecessary you should explain your reasons in your answer. Thanks – pedram bashiri Oct 18 '18 at 19:26
  • 1
    @pedram bashiri, could you please point out what is the reason for this warning? The only thing I see wrong about using javadoc comment like this is that it breaks the convention. – Dhunju_likes_to_Learn Oct 19 '18 at 01:06
0

To me it seems like the right place for this comment is alongside method getFormattedName() because your comment explains the functionality of that method not the reason you're calling it.

pedram bashiri
  • 1,286
  • 15
  • 21
  • I changed the question to reflect what that piece of code does. I took a simple example here but in many cases I need to put a long comment describing what a block of code does. And often I need to use @link to link to other places in code so that it is easier to follow/understand the comment. – Dhunju_likes_to_Learn Oct 19 '18 at 01:02
  • you can use @link in any type of comments. Look at https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html "This tag [@link] is valid in all documentation comments: overview, module, package, class, interface, constructor, method and field". This is the right format {@link package.class#member label } – pedram bashiri Oct 19 '18 at 16:26
  • that would've been perfect! But when I tested using {@link} with one line comment but it doesn't link :( . Also, spec says any type of "documentation" comments. – Dhunju_likes_to_Learn Oct 25 '18 at 16:57