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

How to add package level comments in Javadoc?

提问by Anil Kumar.C

I am using CheckStyle, FindBugs, and PMDto validate my Java code. I have fixed almost all the bugs caught by these tools.

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

I am not able to understand how to write "package comment" which is a bug caught by checkstyle. I have gone through the documentation of CheckStyle, but I don't understand it.

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

Could someone help me in writing a package level comment in Java?

有人可以帮助我用 Java 编写包级注释吗？

回答by Thomas Owens

You have to make a package.htmlpage located within the package. You can read about the contents and structure of this file on the How to Write Doc Comments for the Javadoc Tool page.

您必须package.html在包内创建一个页面。您可以在How to Write Doc Comments for the Javadoc Tool 页面上阅读有关此文件的内容和结构的信息。

回答by Carlos

By using a package.htmlfile for your comments. Please see this document: How to Write Doc Comments for the Javadoc Tool.

通过使用package.html文件进行评论。请参阅此文档：如何为 Javadoc 工具编写文档注释。

回答by GHad

1. Create a file package-info.javain your package to document
2. Add the package descriptor
3. Add a comment (/** ...*/) before the package declaration

1. package-info.java在你的包中创建一个文件来记录
2. 添加包描述符
3. 在包声明前添加注释 (/** ...*/)

The following link provides more information: http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html

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

It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems

建议使用 package-info.java（如果存在）代替 javadoc 和其他类似文档生成系统的 package.html

Package wide annotations will also be declared at package-info.java

包范围的注释也将在 package-info.java 中声明

Greetz, GHad

格雷茨，GHa

回答by duffymo

Google found this as the first hit:

谷歌发现这是第一次命中：

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

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

You just create a file named package.html in each package.

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

回答by Michael Borgwardt

Package-level javadoc comments are placed in a file named package-info.javainside the package directory. It contains the comment and a package declaration:

包级 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;

This is documented here: Package Comment Files

这在此处记录：包注释文件

回答by pavanlimo

You can add documentation at package level.

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

From Sun documentation:

从Sun 文档：

Typically package-info.java contains only a package declaration, preceded immediately by the annotations on the package. While the file could technically contain the source code for one or more package-private classes, it would be very bad form.

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

It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems. If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java. In this way, package-info.java becomes the sole repository for package level annotations and documentation. If, in future, it becomes desirable to add any other package-level information, this file should prove a convenient home for this information.

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

回答by Aravind Yarram

There are two ways of adding package level documentation using javadoc:

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

1. package-info.java
   • Only from 5.0
   • Preferred way
   • Can contain a package declaration, package annotations, package comments and Javadoc tags
2. package.html
   • Any Java version
   • Can notcontain package declaration and/or package annotations

1. 包信息.java
   • 仅从 5.0
   • 首选方式
   • 可以包含包声明、包注释、包注释和 Javadoc 标签
2. 包.html
   • 任何 Java 版本
   • 可以不包含包声明和/或注解包

More details and examples are here. Which one to use: Javadoc: package.html or package-info.java

更多细节和例子在这里。使用哪一个：Javadoc：package.html 或 package-info.java