diff --git a/docs/book/Appendix-Javadoc.md b/docs/book/Appendix-Javadoc.md index 56d62c40..50dc8c2e 100644 --- a/docs/book/Appendix-Javadoc.md +++ b/docs/book/Appendix-Javadoc.md @@ -3,25 +3,19 @@ # 附录:文档注释 -编写代码文档的最大问题可能是维护该文档。如果文档和代码是分开的,那么每次更改代码时更改文档都会变得很繁琐。解决方案似乎很简单:将代码链接到文档。最简单的方法是将所有内容放在同一个文件中。然而,要完成这完整的画面,您需要一个特殊的注释语法来标记文档,以及一个工具来将这些注释提取为有用的表单中。这就是Java所做的。 +编写代码文档的最大问题可能是维护该文档。如果文档和代码是分开的,每次更改代码时都要很繁琐地再去更改文档。解决方案似乎很简单:将代码链接到文档。最简单的方法是将所有内容放在同一个文件中。然而,要完成这个任务,需要一个特殊的注释语法来标记文档,以及一个工具将这些注释提取为有用的形式,这就是Java所做的。 提取注释的工具称为Javadoc,它是 JDK 安装的一部分。它使用Java编译器中的一些技术来寻找特殊的注释标记。它不仅提取由这些标记所标记的信息,还提取与注释相邻的类名或方法名。通过这种方式,您就可以用最少的工作量来生成合适的程序文档。 -Javadoc输出为一个html文件,您可以使用web浏览器查看它。对于Javadoc,您有一个简单的标准来创建文档,因此您可以期望所有Java libraries都有文档。 +Javadoc的输出是一个html文件,可以用web浏览器查看它。有了Javadoc,就有一个简单的标准来创建文档,因此你可以期望所有Java库都有文档。 -此外,您可以编写自己的Javadoc处理程序doclet,对于 Javadoc(例如,以不同的格式生成输出)。 +此外,你可以编写自己的Javadoc处理程序doclet,对javadoc处理的信息做特殊的处理(例如以不同的格式生成输出)。 以下是对Javadoc基础知识的介绍和概述。在 JDK 文档中可以找到完整的描述。 ## 句法规则 -所有Javadoc指令都发生在以 **/**** 开头(但仍然以 ***/** 结尾)的注释中。 - -使用Javadoc有两种主要方法: - -嵌入HTML或使用“doc标签”。独立的doc标签是指令它以 **@** 开头,放在注释行的开头。(然而,前面的 ***** 将被忽略。)可能会出现内联doc标签 - -Javadoc注释中的任何位置,也可以,以一个 **@** 开头,但是被花括号包围。 +所有Javadoc指令都发生在以 `/**` 开头(但仍然以 `*/`)结尾)的注释中。使用Javadoc有两种主要方法:嵌入HTML或使用“doc标签”。独立的doc标签是以 **@** 开头并且放在注释行的开头的指令(注释行开头的`*`将被忽略)。内联的doc标签可以出现在Javadoc注释的任何位置,它也以 `@` 开头,但被花括号包围。 有三种类型的注释文档,它们对应于注释前面的元素:类、字段或方法。也就是说,类注释出现在类定义之前,字段注释出现在字段定义之前,方法注释出现在方法定义之前。举个简单的例子: @@ -37,11 +31,7 @@ public class Documentation1 { ``` -Javadoc处理注释文档仅适用于 **公共** 和 **受保护** 的成员。 - -默认情况下,将忽略对 **私有成员** 和包访问成员的注释(请参阅["隐藏实现"](/docs/book/07-Implementation-Hiding.md)一章),并且您将看不到任何输出。 - -这是有道理的,因为仅客户端程序员的观点是,在文件外部可以使用 **公共成员** 和 **受保护成员** 。 您可以使用 **-private** 标志和包含 **私人** 成员。 +Javadoc仅处理 **公共成员** 和 **继承访问权限成员** 的注释文档。 默认情况下,将忽略对 **私有成员** 和**包访问权限成员**的注释(请参阅["隐藏实现"](/docs/book/07-Implementation-Hiding.md)一章),并且你将看不到任何输出。 这是有道理的,因为从客户端程序员的视角看,在文件外部只有 **公共成员** 和 **继承访问权限成员** 是可用的。 你可以使用 **-private** 标志来包含 **私有成员**。 要通过Javadoc处理前面的代码,命令是: @@ -49,11 +39,11 @@ Javadoc处理注释文档仅适用于 **公共** 和 **受保护** 的成员。 javadoc Documentation1.java ``` -这将产生一组HTML文件。 如果您在浏览器中打开index.html,您将看到结果与所有其他Java文档具有相同的标准格式,因此用户对这种格式很熟悉,并可以轻松地浏览你的类。 +这将产生一组HTML文件。如果你在浏览器中打开index.html,将看到输出的结果与其他Java文档具有相同的标准格式,因此使用者对这种格式很熟悉,并可以轻松地浏览你的类。 ## 内嵌 HTML -Javadoc传递未修改的HTML代码,用以生成的HTML文档。这使你可以充分利用HTML。但是,这样做的主要目的是让你格式化代码,例如: +Javadoc不作修改地将HTML代码传递到生成的HTML文档。这使你可以充分利用HTML。但是这样做的主要目的是让你格式化代码,例如: ```java // javadoc/Documentation2.java @@ -64,7 +54,7 @@ Javadoc传递未修改的HTML代码,用以生成的HTML文档。这使你可 public class Documentation2 {} ``` -您你也可以像在其他任何Web文档中一样使用HTML来格式化说明中的文字: +你也可以像在其他任何Web文档中一样使用HTML来格式化说明中的文字: ```java // javadoc/Documentation3.java @@ -78,7 +68,7 @@ public class Documentation2 {} public class Documentation3 {} ``` -请注意,在文档注释中,Javadoc删除了行首的星号以及前导空格。 Javadoc重新格式化了所有内容,使其符合标准文档的外观。不要将诸如 \