如何在Javadoc中添加包级别注释？

Question

我正在使用CheckStyle，FindBugs和PMD来验证我的Java代码。我已经修复了这些工具捕获的几乎所有错误。

我无法理解如何编写“包评论”，这是checkstyle捕获的错误。我已经阅读了CheckStyle的文档，但我不明白。

有人可以帮我编写Java中的包级别注释吗？

Answer 1

包级别的javadoc注释放在包目录中名为package-info.java的文件中。它包含注释和包声明：

/**
 * Provides the classes necessary to create an applet and the classes an applet uses 
 * to communicate with its applet context. 
 * <p>
 * The applet framework involves two entities: 
 * the applet and the applet context. An applet is an embeddable window (see the 
 * {@link java.awt.Panel} class) with a few extra methods that the applet context 
 * can use to initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

此处记录了这些内容：Package Comment Files

Answer 2

1. 在包中创建文件package-info.java以记录
2. 添加包描述符
3. 在包声明
之前添加注释（/ ** ... * /）

以下链接提供了更多信息：http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html

  

建议   package-info.java，如果它存在，   取代package.html   javadoc和其他类似的   文档生成系统

包广泛注释也将在package-info.java

中声明

格尔茨， GHAD

Answer 3

您必须在包中创建package.html页面。您可以在How to Write Doc Comments for the Javadoc Tool page上了解此文件的内容和结构。

Answer 4

使用javadoc添加包级别文档有两种方法：

1. package-info.java
   • 仅限于5.0
   • 首选方式
   • 可以包含包声明，包注释，包注释和Javadoc标记
2. package.html的
   • 任何Java版本
   • 不可以包含包声明和/或包注释

更多详情和示例是here。使用哪一个：Javadoc: package.html or package-info.java

Answer 5

谷歌发现这是第一个打击：

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

您只需在每个包中创建一个名为package.html的文件。

Answer 6

使用 package.html 文件进行评论。请参阅此文档：How to Write Doc Comments for the Javadoc Tool。

Answer 7

您可以在包级别添加文档。

来自Sun documentation：

通常，package-info.java只包含一个包声明，紧接在包的注释之前。虽然该文件在技术上可以包含一个或多个包私有类的源代码，但它的形式会非常糟糕。

建议package-info.java（如果存在）取代package.html用于javadoc和其他类似的文档生成系统。如果存在此文件，则文档生成工具应在package-info.java中的（可能带注释的）包声明之前查找包文档注释。通过这种方式，package-info.java成为包级别注释和文档的唯一存储库。如果将来需要添加任何其他包级信息，则该文件应该是此信息的便利之家。