为什么 IntelliJ IDEA 会警告此文件 javadoc 悬空？

Question

我正在使用 IntelliJ IDEA，并尝试在文件顶部添加一个 Javadoc 注释，如下所示：

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

但是 IntelliJ 给了我警告“悬空的 Javadoc 评论”。是什么让这条评论悬而未决？我想因为它用@file 标记，所以它应该在文件的开头。

Answer 1

以防万一，如果您有兴趣删除这个悬空的 JavaDoc 注释检查，您可以通过以下方式禁用它：

1. 打开首选项
2. 导航到编辑器 --> 检查
3. 在右侧菜单列表下，选择 Java --> JavaDoc
4. 取消选中“悬空 Javadoc 注释”

Answer 2

如果您将 Javadoc 注释放在任何注释之后，您也会看到这一点。

例如：

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

相反，Javadoc 必须先于一切才能收到“在此文件中未发现错误”的批准印章：

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

Answer 3

Javadoc 没有@file 或@date 标签。相反，您应该标记该类。

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

看：

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

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