为什么 IntelliJ IDEA 会警告该文件 javadoc 悬空？答案

【问题标题】：Why does IntelliJ IDEA give a warning that this file javadoc is dangling?为什么 IntelliJ IDEA 会警告该文件 javadoc 悬空？
【发布时间】：2017-10-08 00:54:42
【问题描述】：

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

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

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

【问题讨论】：

标签： java intellij-idea javadoc

【解决方案1】：

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

【讨论】：

啊，我明白了。这里的标准目前基于 Doxygen，我将不得不与我的同事讨论更新它。

【解决方案2】：

花点时间阅读此警告的扩展帮助，强调我的：

报告悬空的 Javadoc cmets。如果 Javadoc cmets 不属于任何类、方法或字段，则它们是悬空的。例如，具有自己的 Javadoc cmets 的方法声明之间的 Javadoc 注释。

您的 Javadoc 注释不属于类、方法或字段，因此它确实是悬空的。 @file 标签doesn't exist，所以添加是多余的。

或者，您可以删除一个星号并且没有有 Javadoc，从而使 IntelliJ 在这件事上保持沉默...

【讨论】：

【解决方案3】：

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

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

【讨论】：

【解决方案4】：

如果您将 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 {
}

【讨论】：

【解决方案5】：

Intellij Idea 给你“Dangling Javadoc comment”的警告，

1-如果您在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-如果您将 Javadoc cmets 放在类级注释之后：

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

3-如果您使用了 JavaDoc 无法理解的不适当标签，例如 @file 或 @date。

虽然您可以通过省略第一行中的一个星号来跳过这些警告或将 Java-doc 注释更改为常规注释，但我强烈建议您使用 Java-docs，它很快就会非常有用并生成 HTML 中的标准文档.

【讨论】：