mirror of
https://github.com/LingCoder/OnJava8.git
synced 2026-08-27 00:13:28 +08:00
55 lines
2.9 KiB
Markdown
55 lines
2.9 KiB
Markdown
[TOC]
|
||
|
||
<!-- Appendix: Javadoc -->
|
||
# 附录:文档注释
|
||
|
||
编写代码文档的最大问题可能是维护该文档。如果文档和代码是分开的，那么每次更改代码时更改文档都会变得很繁琐。解决方案似乎很简单：将代码链接到文档。最简单的方法是将所有内容放在同一个文件中。然而，要完成这完整的画面，您需要一个特殊的注释语法来标记文档，以及一个工具来将这些注释提取为有用的表单中。这就是Java所做的。
|
||
|
||
提取注释的工具称为Javadoc，它是 JDK 安装的一部分。它使用Java编译器中的一些技术来寻找特殊的注释标记。它不仅提取由这些标记所标记的信息，还提取与注释相邻的类名或方法名。通过这种方式，您就可以用最少的工作量来生成合适的程序文档。
|
||
|
||
Javadoc输出为一个html文件，您可以使用web浏览器查看它。对于Javadoc，您有一个简单的标准来创建文档，因此您可以期望所有Java libraries都有文档。
|
||
|
||
此外，您可以编写自己的Javadoc处理程序doclet，对于 Javadoc（例如，以不同的格式生成输出）。
|
||
|
||
以下是对Javadoc基础知识的介绍和概述。在 JDK 文档中可以找到完整的描述。
|
||
|
||
## 句法规则
|
||
|
||
所有Javadoc指令都发生在以 **/**** 开头(但仍然以 ***/** 结尾)的注释中。
|
||
|
||
使用Javadoc有两种主要方法:
|
||
|
||
嵌入HTML或使用“doc标签”。独立的doc标签是指令它以 **@** 开头，放在注释行的开头。(然而，前面的 ***** 将被忽略。)可能会出现内联doc标签
|
||
|
||
Javadoc注释中的任何位置，也可以，以一个 **@** 开头，但是被花括号包围。
|
||
|
||
有三种类型的注释文档，它们对应于注释前面的元素:类、字段或方法。也就是说，类注释出现在类定义之前，字段注释出现在字段定义之前，方法注释出现在方法定义之前。举个简单的例子:
|
||
|
||
```java
|
||
|
||
// javadoc/Documentation1.java
|
||
/** 一个类注释 */
|
||
public class Documentation1 {
|
||
/** 一个属性注释 */
|
||
public int i;
|
||
/** 一个方法注释 */
|
||
public void f() {}
|
||
}
|
||
|
||
```
|
||
|
||
Javadoc处理注释文档仅适用于 **公共** 和 **受保护** 的成员。
|
||
|
||
默认情况下，将忽略对 **私有成员** 和包访问成员的注释（请参阅["隐藏实现"](/docs/book/07-Implementation-Hiding.md)一章），并且您将看不到任何输出。
|
||
|
||
这是有道理的，因为仅客户端程序员的观点是，在文件外部可以使用 **公共成员** 和 **受保护成员** 。 您可以使用 **-private** 标志和包含 **私人** 成员。
|
||
|
||
要通过Javadoc处理前面的代码，命令是：
|
||
|
||
**javadoc Documentation1.java**
|
||
|
||
这将产生一组HTML文件。 如果您在浏览器中打开index.html，您将看到结果与所有其他Java文档具有相同的标准格式，因此用户对这种格式很熟悉，并可以轻松地浏览您的类。
|
||
|
||
<!-- 分页 -->
|
||
|
||
<div style="page-break-after: always;"></div> |