Hi，大家好，我是编程小6，很荣幸遇见你，我把这些年在开发过程中遇到的问题或想法写出来，今天说一说Javadoc 综合指南,希望能够帮助你!!!。

按照这些简单的指南生成干净、动态的文档。

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="http://www.example.com">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 的说法，这是标签的首选顺序：

1. author
2. version
3. param
4. return
5. throws
6. see
7. since
8. serial
9. 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 文档提供了许多控制台内文档生成示例。

最后的想法

虽然这个过程一开始可能看起来很乏味，但要为干净、可访问的文档付出很小的代价。

快乐评论！

今天的分享到此就结束了，感谢您的阅读，如果确实帮到您，您可以动动手指转发给其他人。