Javadoc之package注释 package.html

转自：http://www.rsky.com.cn/Article/java/200603/535.html

我们使用Javadoc生成API文档时，如果要在包的摘要文件(package-summary.html)中添加自定义内容，我们必须在该包下包含一个package.html文件，在该文件中包含你要描述包的信息，这个文件是用html描述的。Javadoc在进行处理时，会自动提取package.html文件中body元素直接的内容，并将其加入到package-summary.html文件中，最后将包描述的第一个语句放置到overview-summary.html文件中，做为包的简短描述。下面让我们看看一个例子吧。

我们在net.jetmaven这个包下新建一个package.html文件，内容如下：

首先关于这个包的描述信息都在package.html文件的body元素之间，这些信息将会被Javadoc自动提取。这里还有点说明，就是body元素中的第一个语句将会作为包的简短描述，被添加到overview-summary.html文件中，同时添加到package-summary.html头部，都作为对包的简短描述，这里有一个问题，就是Javadoc处理第一个句子是以“.”为句子分割符，而不是“。”（没有考虑国际化），如果你使用中文注释的话一定要注意这点，不然不会达到你想要的效果。下面就是包描述的第一个语句在API文档中出现的两个位置：

overview-summary.html文件中的包描述：

package-summary.html文件中对包的描述。

在package.html文件body元素中的所有内容也会显示在package-summary.html文件中，在package-summary.html会添加一个Description的超级连接，连接到该包的具体描述信息（文件末尾）。

一份好的Java API应该包含包的描述信息，这样可以更容易被人理解，同时也更专业，建议应该在每个包下都应该包含一个package.html文件，通过以上的简单讲解，希望大家能使用好package.html文件。为了方便大家创建package.html，你可以下载package.html模板，只需修改一下即可，在IDEA中，你可以创建一个package.html的文件模板，这样就可以更方便你创建package.html文件啦。

package.html文件模板：右击下载。