java java.doc_使用 javadoc 自动生成 Java 文档

Java 的注释，单行，多行的语法就不在赘述了。

javadoc tags

给 Java 源码文件书写注释，使用常见的 Java 注释可以实现一些，也可以通过如下的 Javadoc 的 Tags 来实现一些特殊的比如跳转，参数返回值等特殊标记。

javadoc 标记有如下一些：

@author 作者名，一般不推荐使用，git blame 基本上能够找到每一行代码的作者

@version 版本号

@see 跳转到相关类或者主题

@param 对方法中某参数的说明

@return 对方法返回值的说明

@exception 对方法可能抛出的异常进行说明

不过已经不建议在 Java 源文件中使用 @author 标记，现代的 git 完全能够满足模块作者的追溯，甚至可以精确到每一行的作者。

Package doc

上面的方法可以给类，方法，参数等等编写注释，如果要给一个包添加注释，就需要额外添加 package-info.java 的文件。

从 Java 1.5 版本开始可以在包下新建一个名为 package-info.java 的文件，在这个文件中可以使用标准 Java 注释来给 package 书写文档：

com/foo/package-info.java:

/**

* com.foo is a group of bar utils for operating on foo things.

*/

package com.foo;

//rest of the file is empty

注释中的代码

如果要在 javadoc 中书写代码，尤其是想要展示一些例子的时候，不可避免的会用到 以及 @ 等等特殊的符号。Javadoc 默认是 html 的 tag 来渲染格式，所以这种情况下有

 和  选择，然后 javadoc 还提供了 {@code} 语法。这三个方式都可以用来注释代码，但各自又不相同。

使用 pre 标签

 标记是 html 默认的格式化标签，如果使用 

 标签，那么所有的 html 的标记都需要转义。

/**

*

* public class JavadocTest {

* // indentation and line breaks are kept

*

* @SuppressWarnings

* public List<String> generics(){

* // '@', '' have to be escaped with HTML codes

* // when used in annotations or generics

* }

* }

*

*/

public class PreTest {}

命令行的使用

Java 安装完成之后在 Java Path 的目录中自带了 javadoc 这个命令行，如果不想使用 maven-javadoc-plugin 可以使用这个命令来生成 javadoc.

用法：

javadoc [options] [packagenames] [sourcefiles]

选项：

-public 仅显示 public 类和成员

-protected 显示 protected/public 类和成员 (缺省)

-package 显示 package/protected/public 类和成员

-private 显示所有类和成员

-d 输出文件的目标目录

-version 包含 @version 段

-author 包含 @author 段

-splitindex 将索引分为每个字母对应一个文件

-windowtitle 文档的浏览器窗口标题

在 Intellij 中调整文件头

Intellij 默认会在创建文件的时候给文件添加一些注释，这些注释可以在如下的设置中修改：

File -> Setting -> Editor-> File and Code Template-> File Header