为什么IntelliJ IDEA会发出警告，说这个文件javadoc是悬空的？

Question

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

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

但IntelliJ给了我警告“Dangling Javadoc评论”。是什么让这个评论晃来晃去？我想因为它用@file标记，它应该在文件的开头。

Answer 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

Answer 2

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

  

悬挂Javadoc评论的报道。如果它们不属于任何类，方法或字段，那么Javadoc的评论就会悬空。例如，在具有自己的Javadoc注释的方法声明之间进行Javadoc注释。

您的Javadoc评论不属于该类，方法或字段，因此它确实悬空。 @file代码doesn't exist，所以添加它是多余的。

或者，您可以删除一个星号而不拥有Javadoc，从而使IntelliJ在此事上保持沉默......

Answer 3

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

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

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

Answer 5

Intellij Idea 为您提供“悬空 Javadoc 注释”的警告，

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 注释放在类级注释之后：

@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 格式的标准文档.