Warning: Dangling Javadoc comment

Question

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.

Gabelle

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. – Crampton

Answer 1

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.

Appellative

The IDE ought to provide this as an auto-fix option. Or detect it as a distinct error like "javadoc between attribute and declaration" – Purplish

Answer 2

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}.

Commixture

but with one-line comment, using {@link FORMAT_NAME} won't link as it does with Javadoc comment. I checked this on Android Studio IDE. – Gabelle

@Gabelle That may be so, but the fact remains that where you have placed that comment is an incorrect spot for a javadoc comment. – Semiskilled

@nasch, agreed. – Gabelle

Answer 3

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 /**.

Taintless

Answer 4

Just replace "Dangling Javadoc Comment" with block comment.

Gareri

Then you cannot use {@link } - that is indexed by IDEs only in javadocs. – Reprobate

@Reprobate 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. – Gareri

Answer 5

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

Listed

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. – Moltke

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 – Moltke

@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. – Gabelle

Answer 6

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.

Moltke

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. – Gabelle

you can use @link in any type of comments. Look at docs.oracle.com/en/java/javase/11/docs/specs/… "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 } – Moltke

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. – Gabelle