按照这些简单的指南生成干净、动态的文档。
Javadoc 到底是什么？
文档是开发人员最好的朋友。 但是，该文档最初是如何创建的呢？ 对于许多 Java 程序，答案是 Javadoc。
Javadoc 是 Oracle 拥有的一个易于使用的工具，它解析您的 Java 代码并生成干净的 API 文档，您和其他人可以使用这些文档来更好地理解您的程序。 以下指南将准确地教您如何编写 Javadoc 理解的注释以及如何访问所述文档。
Javadoc 注释的一般格式
要将 Javadoc 注释与标准 Java 注释区分开来，请在块注释的开头使用两个星号而不是一个星号。
// single-line comment/*
* standard block comment
*//**
* Javadoc comment
*/ 注意 ：单行 Javadoc 注释不支持语法。
这些注释通常由两个不同的部分组成：第一个是对注释所属的字段、方法或类的一般描述，第二个是由 @ 符号表示的标签列表，为文档提供诸如 返回类型、相关文件或版本信息。
/**
* This is an example method that does something super, super
* important.
*
* @return int
* @throws Exception
*/ 注意 ：上面示例中两个部分之间的空格在技术上不是必需的，但包含它是一种很好的做法。
此外，Javadoc 注释行有 80 个字符的限制。
我应该在哪里包含 Javadoc 注释？
Javadoc 注释主要分为三类：
- 现场评论
- 方法注释
- 课堂评论
一个好的经验法则是为所有类和方法创建详细的 Javadoc 注释，但不要注释大多数字段，除非它们经常以不明显的方式使用或名称模糊。
字段注释
/**
* A really important variable
*/ private String superImportant; 方法注释
/**
* Prints a specified number and returns a smiley face.
*
* @param num integer to be printed
* @param shouldPrint whether or not to print the number
* @return smiley face
*/ String exampleMethod (int num, boolean shouldPrint) {
if (shouldPrint) System.out.print("Your number is: " + num);
return ":)";
} class 评论
/**
* Does nothing, but is a beautiful example.
*
* @author Sophia Hubscher
* @version 1.0
*/public class exampleClass {
} 注意 ：Javadoc 注释遵循继承规则，这意味着不需要为继承的类、方法或字段编写 Javadoc 注释。
块与内联标签
到目前为止，我们看到的所有标签都是 @tag 形式的，但也有很多其他形式的 {@tag} 。 这两者之间的区别在于，虽然第一种类型（块标签）始终是其代码行中的唯一信息，但括号内的标签（内联标签）与其他 字符串 、标签和信息一起使用。
/**
* Example method that does something really cool and exciting.
*
* @deprecated As of v 2.0, replaced by {@link #otherExample(int)}
*/
Javadoc 标记
所以您知道如何构建 Javadoc 注释，但是所有这些标签呢？ 这是它们的列表，从最常用的开始。
键：名称 | 语法 | 解释
- 参数 | @param parameterName [参数描述] | 在方法注释中用于解释其每个参数。 如示例方法注释中所示，每个参数使用一个参数标记。
- 返回 | @return [返回值说明]| 除非返回类型为 void ，否则在方法注释中使用。
- 见 | @见参考| @see 后面可以跟一个字符串、外部链接或对代码另一部分的引用。
// the three types of @see tags@see "This is an example string."
@see <a href="#34;>Label</a>
@see package.class#member label - 作者 | @作者姓名|在类注释中使用以指定作者。
- 版本 | @版本迭代|用于跟踪代码的版本。
- 自从| @自日期|类似于版本，但跟踪日期而不是版本号。
- 抛出 | @抛出异常|表示方法抛出的异常。可以替换为 @exception ，但 @throws 是标准的。
- 弃用 | @不推荐使用的文本 |表示不应再使用的已弃用代码。
- {代码} | {@代码文本} |以代码字体显示文本。
{@code Here’s some text!} 会变成：“Here’s some text!”进入这个“这里有一些文字！”在您的文档中。
- {链接} | {@link package.class#member 标签} |以代码字体将链接插入到文档中。
- {linkplain} | {@linkplain package.class#member 标签} |以纯字体将链接插入到文档中。
- {docRoot} | {@docRoot} |提供根目录的 相对路径 。
- {inheritDoc} | {@inheritDoc} |从最近的可继承类或可实现接口继承文档。
- 连载 | @序列描述 |用于默认可序列化字段
- 序列数据 | @serialData 描述|当通过 writeObject() 或 writeExternal() 方法写入数据时使用。
- 序列字段 | @serialField 名称类型描述 |为 ObjectStreamField 组件提供注释。
- {值} | {@value package.class#field} |显示常量字段的值。
提示：检查是否有任何方法可以自动生成 Javadoc 注释的大纲，例如 JDeveloper 的“Source → Add Javadoc Comments”工具！
标签应该按任何特定顺序排列吗？
是的！ 根据 Javadoc 的所有者 Oracle 的说法，这是标签的首选顺序：
- author
- version
- param
- return
- throws
- see
- since
- serial
- depreciated
因为内联标签不需要自己的代码行，所以只要在适当的地方使用它们，不用担心这个顺序。
所有的 HTML 是怎么回事？
为了让您对文档的外观和感觉有所控制，Javadoc 为您提供了使用 HTML 标记来设置文本样式的选项！
/**
* <h1>Fun heading!</h1>
* <p>
* Here's a super cool description of my super cool class!
* </p>
*
* @author Sophia Hubscher
* @version 1.0
*/ 关于对齐的说明
尽管在垂直对齐代码方面我们都有自己的偏好，但对于 Javadoc，任何事情都会发生。 所以，做任何让你的船漂浮的事情。
/**
* Feel free to do this!
*
* @param number a really cool number
* @param coolerNumber an even cooler number
* @return the sum (a.k.a the coolest number ever)
*//**
* Or this!
*
* @param number a really cool number
* @param coolerNumber an even cooler number
* @return the sum (a.k.a the coolest number ever)
*/ 访问文档
你做到了！您的代码已被注释，您已准备好查看您的全新文档！但是怎么做？
按照以下步骤获取您最喜欢的 IDE ，生成文档后，您始终可以通过导航到新生成的 index.html 文件来查看它。
开发人员
构建 → Javadoc
智能
工具 → 生成 Javadoc → 确定
编辑器内：将鼠标悬停在您的代码上，然后选择 F1（或 Ctrl+Q 用于 Windows/ Linux ）。
jGRASP
文件 → 生成文档
蚀
项目 → 生成 Javadoc → 完成
网豆
窗口 → IDE 工具 → Javadoc 文档
编辑器内：将鼠标悬停在您的代码上，然后为 Windows/Linux 选择 Ctrl+Shift+Space 或为 macOS 选择 Cmd+Shift+。
蓝J
工具 → 产品文档
命令行
如果您不想使用 IDE，Oracle 文档提供了许多控制台内文档生成示例。
最后的想法
虽然这个过程一开始可能看起来很乏味，但要为干净、可访问的文档付出很小的代价。
快乐评论！
