Skip to content

Appendix: Javadoc翻译修改 #467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 8, 2020
Merged

Appendix: Javadoc翻译修改 #467

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 13 additions & 23 deletions docs/book/Appendix-Javadoc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,25 +3,19 @@
<!-- Appendix: Javadoc -->
# 附录:文档注释

编写代码文档的最大问题可能是维护该文档。如果文档和代码是分开的，那么每次更改代码时更改文档都会变得很繁琐。解决方案似乎很简单：将代码链接到文档。最简单的方法是将所有内容放在同一个文件中。然而，要完成这完整的画面，您需要一个特殊的注释语法来标记文档，以及一个工具来将这些注释提取为有用的表单中。这就是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注释的任何位置，它也以 `@` 开头，但被花括号包围。

有三种类型的注释文档，它们对应于注释前面的元素:类、字段或方法。也就是说，类注释出现在类定义之前，字段注释出现在字段定义之前，方法注释出现在方法定义之前。举个简单的例子:

Expand All @@ -37,23 +31,19 @@ public class Documentation1 {

```

Javadoc处理注释文档仅适用于 **公共** 和 **受保护** 的成员。

默认情况下，将忽略对 **私有成员** 和包访问成员的注释（请参阅["隐藏实现"](/docs/book/07-Implementation-Hiding.md)一章），并且您将看不到任何输出。

这是有道理的，因为仅客户端程序员的观点是，在文件外部可以使用 **公共成员** 和 **受保护成员** 。 您可以使用 **-private** 标志和包含 **私人** 成员。
Javadoc仅处理 **公共成员** 和 **继承访问权限成员** 的注释文档。 默认情况下，将忽略对 **私有成员** 和**包访问权限成员**的注释（请参阅["隐藏实现"](/docs/book/07-Implementation-Hiding.md)一章），并且你将看不到任何输出。 这是有道理的，因为从客户端程序员的视角看，在文件外部只有 **公共成员** 和 **继承访问权限成员** 是可用的。 你可以使用 **-private** 标志来包含 **私有成员**。

要通过Javadoc处理前面的代码，命令是：

```cmd
javadoc Documentation1.java
```

这将产生一组HTML文件。 如果您在浏览器中打开index.html，您将看到结果与所有其他Java文档具有相同的标准格式，因此用户对这种格式很熟悉，并可以轻松地浏览你的类。
这将产生一组HTML文件。如果你在浏览器中打开index.html，将看到输出的结果与其他Java文档具有相同的标准格式，因此使用者对这种格式很熟悉，并可以轻松地浏览你的类。

## 内嵌 HTML

Javadoc传递未修改的HTML代码，用以生成的HTML文档。这使你可以充分利用HTML。但是，这样做的主要目的是让你格式化代码，例如：
Javadoc不作修改地将HTML代码传递到生成的HTML文档。这使你可以充分利用HTML。但是这样做的主要目的是让你格式化代码，例如：

```java
// javadoc/Documentation2.java
Expand All @@ -64,7 +54,7 @@ Javadoc传递未修改的HTML代码，用以生成的HTML文档。这使你可
public class Documentation2 {}
```

您你也可以像在其他任何Web文档中一样使用HTML来格式化说明中的文字：
你也可以像在其他任何Web文档中一样使用HTML来格式化说明中的文字：

```java
// javadoc/Documentation3.java
Expand All @@ -78,7 +68,7 @@ public class Documentation2 {}
public class Documentation3 {}
```

请注意，在文档注释中，Javadoc删除了行首的星号以及前导空格。 Javadoc重新格式化了所有内容，使其符合标准文档的外观。不要将诸如 \<h1\>或 \<hr\>之类的标题用作嵌入式HTML，因为Javadoc会插入自己的标题，后插入的标题将对其生成的文档产生干扰。
请注意，在文档注释中，Javadoc会删除行首的星号以及前导空格。 Javadoc重新格式化了所有内容，使其符合文档的标准外观。不要将`<h1>` 和`<hr>` 之类的标题用作嵌入式HTML，因为Javadoc会插入自己的标题，你插入的标题将对其产生干扰。

所有类型的注释文档（类，字段和方法）都可以支持嵌入式HTML。

Expand All @@ -88,7 +78,7 @@ public class Documentation3 {}

### @see

这个标签可以将其他的类连接到文档中，Javadoc 将使用 @see 标记超链接到其他文档中，形式为：
这个标签可以将其它的类链接到本文档中。Javadoc 用 `@see` 标签产生链接到其它类的的HTML。格式为：

```java
@see classname
Expand Down Expand Up @@ -144,7 +134,7 @@ public class Documentation3 {}
@param parameter-name description
```

其中parameter-name是方法参数列表中的标识符，description 是可以在后续行中继续的文本。当遇到新的文档标签时，说明被视为完成。@param 标签的可以任意使用，大概每个参数一个。
其中 `parameter-name` 是方法参数列表中的标识符， `description` 是可以在后续行中继续的文本。当遇到新的文档标签时，这个说明被视为结束。`@param`标签可以使用任意次，大概每个参数使用一次。

### @return

Expand All @@ -164,11 +154,11 @@ public class Documentation3 {}
@throws fully-qualified-class-name description
```

fully-qualified-class-name 给出明确的异常分类名称，并且 description （可延续到后面的行内）告诉你为什么这特定类型的异常会在方法调用后出现。
*fully-qualified-class-name* 给出异常类的确切名称，并且 description （可在后面的行内继续展开）告诉你为什么这个特定类型的异常会在方法调用后出现。

### @deprecated

这表示已被改进的功能取代的功能。deprecated 标记表明你不再使用此特定功能，因为将来有可能将其删除。标记为@不赞成使用的方法会导致编译器在使用时发出警告。在Java 5中，@deprecated Javadoc 标记已被 @Deprecated 注解取代（在[注解]()一章中进行了描述）。
表示已被改进的功能取代的功能。deprecated 标记建议你不要再使用此功能，因为将来它有可能被删除。使用标记为 `@deprecated` 的方法会使编译器发出警告。在Java 5中，`@deprecated` Javadoc 标记被 `@Deprecated` *注解* 取代（在[注解]()一章中进行了描述）。

## 文档示例

Expand Down