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