java类的文档

所有 Javadoc 注释都以块注释开头，后跟星号 (/*)，并在块注释出现 (/) 时结束。
或者，每行可以以任意空格和单个星号开头；生成文档文件时将忽略这些。

/**
* Brief summary of this class, ending with a period.
*
* It is common to leave a blank line between the summary and further details.
* The summary (everything before the first period) is used in the class or package
* overview section.
*
* The following inline tags can be used (not an exhaustive list):
* {@link some.other.class.Documentation} for linking to other docs or symbols
* {@link some.other.class.Documentation Some Display Name} the link's appearance can be
* customized by adding a display name after the doc or symbol locator
* {@code code goes here} for formatting as code
* {@literal <>[]()foo} for interpreting literal text without converting to HTML markup
* or other tags.
* Optionally, the following tags Jan be used at the end of class documentation
* (not an exhaustive list):
* @author John Doe
* @version 1.0
* @since 5/10/15
* @see some.other.class.Documentation
* @deprecated This class has been replaced by some.other.package.BetterFileReader
*
* You can also have custom tags for displaying additional information.
* Using the @custom. tag and the -tag custom.:htmltag:"context"
* command line option, you can create a custom tag.
*
* Example custom tag and generation:
* @custom.updated 2.0
* Javadoc flag: -tag custom.updated:a:"Updated in version:"
* The above flag will display the value of @custom.updated under "Updated in version:"
*
*/
public class FileReader {
}

用于类的相同标签和格式也可用于枚举和接口。

Java方法的文档

所有 Javadoc 注释都以块注释开头，后跟星号 (/*)，并在块注释出现 (/) 时结束。
或者，每行可以以任意空格和单个星号开头；生成文档文件时将忽略这些

/**
* Brief summary of method, ending with a period.
* Further description of method and what it does, including as much detail as is
* appropriate. Inline tags such as
* {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
*
* If a method overrides a superclass method, {@inheritDoc} can be used to copy the
* documentation
* from the superclass method
*
* @param stream Describe this parameter. Include as much detail as is appropriate
* Parameter docs are commonly aligned as here, but this is optional.
* As with other docs, the documentation before the first period is
* used as a summary.
*
* @return Describe the return values. Include as much detail as is appropriate
* Return type docs are commonly aligned as here, but this is optional.
* As with other docs, the documentation before the first period is used as a
* summary.
* @throws IOException Describe when and why this exception can be thrown.
* Exception docs are commonly aligned as here, but this is
optional.
* As with other docs, the documentation before the first period
is used as a summary.
* Instead of @throws, @exception can also be used.
* @since 2.1.0
* @see some.other.class.Documentation
* @deprecated Describe why this method is outdated. A replacement can also be specified.
*/

public String[] read(InputStream stream) throws IOException {
return null;
}

包的文档

可以使用名为 package-info.java 的文件在 Javadocs 中创建包级文档。
该文件的格式必须如下。
前导空格和星号可选，通常出现在每一行中以进行格式化

/**
* Package documentation goes here; any documentation before the first period will
* be used as a summary.
* It is common practice to leave a blank line between the summary and the rest
* of the documentation; use this space to describe the package in * as much detail as is appropriate.
* Inline tags such as {@code code here}, {@link * reference.to.other.Documentation}, 
* and {@literal text here} can be used in this documentation.
*/
package com.example.foo;
//The rest of the file must be empty.

在上述情况下，我们必须将此文件 package-info.java 放在 Java 包 com.example.foo 的文件夹中。

链接文档

/**
* You can link to the javadoc of an already imported class using {@link ClassName}.
* You can also use the fully-qualified name, if the class is not already imported:
* {@link some.other.ClassName}
* You can link to members (fields or methods) of a class like so:
* {@link ClassName#someMethod()}
* {@link ClassName#someMethodWithParameters(int, String)}
* {@link ClassName#someField}
* {@link #someMethodInThisClass()} - used to link to members in the current class
* You can add a label to a linked javadoc like so:
* {@link ClassName#someMethod() link text}
* /

使用@see 标签，您可以将元素添加到“另见”部分。 像@param 或者@return 一样，它们出现的地方是不相关的。 规范说你应该在@return 之后写它。

/**
* This method has a nice explanation but you might found further
* information at the bottom.
*
* @see ClassName#someMethod()
*/

这个方法有一个很好的解释，但你可能会发现更多
也可以看看：

Classname.someMethod()

文档中的代码片段

在文档中编写代码的规范方式是使用 {@code} 构造。
如果我们有多行代码，放到 <pre></pre>中

/**
* The Class TestUtils.
* <p>
* This is an {@code inline("code example")}.
* <p>
* You should wrap it in pre tags when writing multiline code.
* <pre>{@code
* Example example1 = new FirstLineExample();
* example1.butYouCanHaveMoreThanOneLine();
* }
* <p>
* Thanks for reading.
* /
class TestUtils {

有时我们可能需要在 javadoc 注释中放入一些复杂的代码。
@ 符号特别有问题。
使用旧的 <code> 标签与 {@literal} 构造一起解决了这个问题。

/**
* Usage:
* class SomethingTest {
* {@literal @}Rule
* public SingleTestRule singleTestRule = new SingleTestRule("test1");
* {@literal @}Test
* public void test1() {
*     //only this test will be executed
* }
* …
* }
**/
class SingleTestRule implements TestRule { }

字段文档

所有 Javadoc 注释都以块注释开头，后跟星号 (/*)，并在块注释出现 (/) 时结束。
或者，每行可以以任意空格和单个星号开头；生成文档文件时将忽略这些。

/**
* Fields can be documented as well.
*
* As with other javadocs, the documentation before the first period is used as a
* summary, and is usually separated from the rest of the documentation by a blank
* line.
*
* Documentation for fields can use inline tags, such as:
* {@code code here}
* {@literal text here}
* {@link other.docs.Here}
* Field documentation can also make use of the following tags:
*
* @since 2.1.0
* @see some.other.class.Documentation
* @deprecated Describe why this field is outdated
*/
public static final String CONSTANT_STRING = "foo";

内联代码文档

除了 Javadoc 文档代码之外，还可以内嵌文档。

单行注释以 //开头，可以放在同一行的语句之后，但不能放在之前。

public void method() {
//single line comment
someMethodCall(); //single line comment after statement
}

多行注释定义在 /* 和 */之间。
它们可以跨越多行，甚至可以位于语句之间。

public void method(Object object) {
/*
multi
line
comment
/object/inner-line-comment*/.method();
}

JavaDocs 是一种特殊形式的多行注释，以 /** 开头。

由于过多的内联注释可能会降低代码的可读性，因此在代码不够自我解释或者设计决策不明显的情况下，应少量使用它们。

Java 代码的文档通常是使用 Javadoc 生成的。
Javadoc 由 Sun Microsystems 创建，目的是从 Java 源代码生成 HTML 格式的 API 文档。
使用 HTML 格式可以方便地将相关文档超链接在一起。

从命令行构建 Javadoc

许多 IDE 支持从 Javadoc 自动生成 HTML；一些构建工具（例如 Maven 和 Gradle）也有可以处理 HTML 创建的插件。

但是，生成 Javadoc HTML 不需要这些工具；这可以使用命令行 Javadoc 工具来完成。

该工具最基本的用法是：

javadoc JavaFile.java

这将从 JavaFile.java 中的 Javadoc 注释生成 HTML。

命令行工具的更实际使用，它将递归读取[source-directory]中的所有java文件，为[package.name]和所有子包创建文档并将生成HTML放在[docsdirectory]中
是：

javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]