黄阶低级 - 《 Java 核心》- 4.9 文档注释 - 修改0次

1、文档注释

1、Java 包含一个很有用的工具，叫做 javadoc ， 可以由源代码生成一个 Html 文档。联机 API 文档也是通过对标准 Java 类库源代码运行 javadoc生成的。
2、如果在源代码中添加专用的定界符 /** 开始的注释，那么很容易生成专业的文档。
3.这种方法可以是代码和注释保存在同一个地方，防止丢失。更改代码后，再次运行 javadoc 即可。

2、注释的插入

javadoc 从下面几个特性中抽取信息：

• 包
• 公有类与接口
• 公有的和受保护的构造器和方法

• 公有的和受保护的域

3、类注释

1、类注释必须在 import 语句之后，在类定义之前。
2、没有必要再而每一行的开始加 * 号，但大部分 IDE 会这么做，自动的。

import java.*;

/**
 * 这是一个 Employee 类
 * 
 * @author swll
 * @version 0.1
 */

public class Employee {
}

4、方法注释

1、方法注释必须放在方法之前，除了通用标记之外，还可以使用 @param ，@return ，@throws 等描述：

/**
* @param ...
* @return ...
* @throws ...
*/
public static int assignID() {
    int r = nextId;
    nextId++;
    return r;
}

5、域注释

只需要对公共域建议注释文档，常只静态常量，其他域建立了文档会暴露信息。

6、通用注释

7、包与概述注释

!! 要想产生包注释，需要在每个包目录中添加一个单独的文件 !!
两种方法：

1. package.html 文件， body 中的内容会全部被提取出来。
2. package-info.java 文件，使用 /* 和 / ，界定外不可以有其他代码。