Why does IntelliJ IDEA give a warning that this file javadoc is dangling?

Question

I'm using IntelliJ IDEA and I tried to add a Javadoc comment at the top of the file like this:

/**
 * @file ProcessJson.java
 * @author Tim Sloane
 * @date 2017-05-09
 */

But IntelliJ gives me the warning "Dangling Javadoc comment." What makes this comment dangling? I thought because it's tagged with @file, it should be at the start of the file.

Answer 1

You will also see this if you placed the Javadoc comment after any annotations.

For example:

@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
@SuppressWarnings({"unused", "WeakerAccess"})
/**  --> Dangling Javadoc warning.
 * This class does great and wonderful things.
 */
public class ClassThatDoesStuff {
}

Instead, the Javadoc must precede everything to receive the "No errors found in this file" seal of approval:

/**
 * This class does great and wonderful things.
 */
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
@SuppressWarnings({"unused", "WeakerAccess"})
public class ClassThatDoesStuff {
}

Answer 2

Just in case, if you are interested in removing this dangling JavaDoc comment inspection, you can do so by disabling that from:

1. Open preferences
2. Navigate to Editor --> Inspections
3. Under the menu list on right, select Java --> JavaDoc
4. Uncheck "Dangling Javadoc comment"

Answer 3

Javadoc has no @file or @date tags. You should be tagging the class, instead.

/**
 * Description of the class goes here.
 * 
 * @author Tim Sloane
 */
public class ProcessJson {

See:

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

Answer 4

Take a bit of time to read the expanded help for this warning, emphasis mine:

Reports dangling Javadoc comments. Javadoc comments are dangling if they don't belong to any class, method or field. For example a Javadoc comment in between method declarations that have their own Javadoc comments.

Your Javadoc comment doesn't belong to the class, or a method, or a field, so it's indeed dangling. The @file tag doesn't exist , so it's superfluous to add at all.

Alternatively, you could remove one asterisk and not have Javadoc, and thus silence IntelliJ on the matter...

Answer 5

Intellij Idea gives you the warning of " Dangling Javadoc comment ",

1-If you insert you classes import declarations after Javadoc :

/**
 * @author Elyas 'Eloy' Hadizadeh Tasbiti
 * Created in 3/16/20, 1:15 PM.
 */

import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;

@Controller
@RequestMapping("/")
public class HomeController
{}

2-If you put your Javadoc comments after class-level annotations:

@Controller
@RequestMapping("/")
/**
 * @author Elyas 'Eloy' Hadizadeh Tasbiti
 * Created in 3/16/20, 1:15 PM.
 */
public class HomeController
{}

3-If you use inappropriate tags such as @file or @date which are not understandable by JavaDoc.

Although you can skip these warnings or change a Java-doc comment to a regular comment by omitting one of the asterisks from the first line, I highly recommend using Java-docs which soon can be very helpful and generates standard documentation in HTML.