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

Question

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

我无法理解如何编写“包注释(package comment)”，这是CheckStyle捕获的一个错误。虽然我已经查阅了CheckStyle的文档，但我仍然不明白。

有人能帮我写一个Java的包级别注释吗？

- Anil Kumar.C

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;

这里有详细的文档：包注释文件

- Michael Borgwardt

---

有趣。关于编写Javadoc注释的页面（请参见我的答案）甚至没有提到这一点。 - Thomas Owens

@Thomas：保持重叠文档的一致更新真是太麻烦了。 - Michael Borgwardt

确实如此。我本来以为Sun（现在是Oracle）会更好地维护文档。特别是因为我已经从事Java开发超过5年了，却从未见过或听说过这种生成包级文档的方法。 - Thomas Owens

@MichaelBorgwardt，有没有办法为javadocs添加“概述”部分？（如http://docs.oracle.com/javase/6/docs/api/overview-summary.html所示） - Pacerier

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

- GHad

---

我之前从未听说过这个方法。你能提供一个描述它的文档链接吗？ - Thomas Owens

@Thomas Owens http://java.sun.com/docs/books/jls/third_edition/html/packages.html @Thomas Owens http://java.sun.com/docs/books/jls/third_edition/html/packages.html - emory

建议对于 javadoc 和其他相似的文档生成系统，如果 package-info.java 文件存在，则该文件应替换 package.html 文件。 - GHad

这些链接真的需要更新，它们已经过时了。 - Andrew S

Answer 3

您需要在包内创建一个名为package.html的页面。您可以在如何为Javadoc工具编写文档注释页面中了解此文件的内容和结构。

- Thomas Owens

---

我想这是因为根本没有提到package-info.java（这是现在首选的变体）。 - Paŭlo Ebermann

Answer 4

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

1. package-info.java
   • 只能在5.0及以上版本中使用
   • 首选方法
   • 可以包含包声明、包注解、包注释和Javadoc标签
2. package.html
   • 任何Java版本均可使用
   • 不能包含包声明和/或包注解

更多细节和示例请参见此处。要使用哪种方法：Javadoc: package.html or package-info.java

- Aravind Yarram

Answer 5

谷歌搜索结果显示：

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

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

- duffymo

---

你将 package-info.html 文件放在哪里？ - Danijel

我认为它们应该放在包的根目录下。尝试一下应该就能明白了。不知道自三年前我回答这个问题以来它有没有改变。 - duffymo

@Danijel，我们不能在包中有子文件夹，对吧... - Pacerier

Answer 6

使用 package.html 文件来编写您的注释。请参阅此文档：如何为Javadoc工具编写文档注释。

- Carlos

Answer 7

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

来自Sun文档：

通常，package-info.java仅包含一个包声明，紧随其后的是包上的注释。虽然该文件在技术上可以包含一个或多个包私有类的源代码，但这将是非常不好的形式。

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

- pavanlimo