Java的注释文档和嵌入式文档

代码文档document，其撰写的最大问题，大概就是对文档的维护。

如果文档与代码是分离的，那么每次修改代码时，都需要修改相应的文档，这相当乏味。

 

为解决这个问题，我们将代码同文档“链接”起来。

1、为达到这个目的，最简单的方法是将所有东西都放在同一个文件内。

2、另外，还必须使用一种特殊的注释语法来标记文档；

3、以及一个工具，用于提取那些注释，并将其转换为有用的形式。

 

---

 

javadoc

javadoc，便是用于提取注释的工具。在下载的jdk（Java developer's kit）里面。

它采用了Java编译器的某些技术，查找程序内的“特殊”注释标签。

它不仅解析由这些标签标记的信息，也将毗邻这些特殊注释的类名或方法名抽取出来。

javadoc输出一个HTML文件，可以通过浏览器查看。

 

javadoc能使我们只需创建和维护单一的源文件，并能自动生成有用的文档。有了javadoc，即有了创建文档的简明直观的标准。

 

拓展：

如果想对javadoc处理过的信息执行特殊的操作，比如产生不同格式的输出，则可以通过编写你自己的被称为doclets的javadoc处理器来实现。

 

下面，我们将对javadoc进行简单的介绍和概述，全面的描述可以同jdk document中的tooldocs找到

---

语法

所有javadoc命令，都只能在“/**”注释中出现，注释结束于“*/”，

javadoc共有三种注释文档，分别对应于注释位置后面的三种元素：

1、类

类注释class comment正好位于类定义之前

2、域

域注释filed comment正好位于域定义之前

3、方法

方法注释method comment正好位于方法定义之前

 

备注：

javadoc只能为public、protected成员进行文档注释，private、包内可访问成员的注释会被忽略，因为只有public、protected成员才能在文件之外使用

 

---

使用javadoc的方式主要有两种

1、使用“文档标签”

独立文档标签，是一些以“@”字符开头的命令，且要置于注释行的最前面

行内文档标签，则可以出现在javadoc注释中的任何位置，同样是以“@”字符开头的命令，但要在括在花括号内

 

备注：

在通过编译器和执行检查后，文档就可以自动更新成文本

/*Output标签：表示输出的开始部分将由这个文件生成，通过这种形式，它会被自动地测试以验证其准确性。

 

2、嵌入式HTML

javadoc通过生成的HTML文档传送HTML命令，则能充分利用HTML，其主要目的是为了对代码进行格式化

 

另外，也可以像在其他Web文档中那样运用HTML，对普通文本安装你自己描述的进行格式化：

 

备注：

在文档注释中，位于每一行开头的星号和前导空格都会被javadoc丢弃，javadoc会对所有内容重新格式化，使其与标准的文档外观一致。

不要再嵌入式HTML中使用标题标签，例如<h1> or <hr>，因为javadoc会插入自己的标题，而你的标题可能会同它们发生冲突。

所有类型的注释文档（类、域、方法），都支持嵌入式HTML