javadoc 是Java开发工具包（JDK）提供的工具，用于从Java源代码创建文档。文档通常以HTML格式创建，内容从源代码文件读取。源代码文件通常有 .java 分机。

示例Java代码

在学习javadoc的过程中，我们将使用下面的Java源代码示例来展示示例，该示例包括基本类、函数、变量等。

public class HelloWorld{        public static void main(String args[])        {                System.out.println("Hello World!");                String name="Poftut.com";                PrintHello(name);        }        public void PrintHello(String name)        {                System.out.println("Hello " + name);        }}

javadoc命令语法

javadoc命令具有以下简单语法，其中包含包、源文件、选项和arg文件。

javadoc PACKAGE|SOURCE_FILE OPTIONS @ARGFILES

• `javadoc`是生成java源代码文档的命令。
• `PACKAGE | SOURCE _FILE`是生成文档的包或源文件名。
• `OPTIONS`启用javadoc的不同行为
• `@ARGFILES`用于为javadoc命令提供参数。

JavaDoc注释

如前所述，javadoc注释是通过使用多行注释和放置一些标记来创建的，以便提供一些数据。我们将使用 /* 对于javadoc注释和 */ 评论结束。阿尔索 * 用于 /* 和 */ 以使注释成为JavaDoc注释。如果不使用它将被认为是一个正常的评论。

/* * @author      İsmail Baydan * @version     1.0 * @since       2014-01-01 * * */public class HelloWorld{        public static void main(String args[])        {                System.out.println("Hello World!");                String name="Poftut.com";                PrintHello(name);        }        public void PrintHello(String name)        {                System.out.println("Hello " + name);        }}

JavaDoc vs单行vs多行注释

在启动JavaDoc之前，我们必须区分Java编程语言中不同类型的注释。让我们检查以下注释类型JavaDoc，单行和多行。

//Single-Line Comment/**Multi-line Comment*//*** JavaDoc Comment*/

JavaDoc标记

JavaDoc使用标签来标识文档。标签将以 @ 签名，然后标签名就来了。下面是标记的基本语法。

@TAG_NAME TAG_VALUE

• `TAG_NAME`是标记的名称，如author、code、exception、param等。
• `TAGu VALUE`是记录给定标记的标记的值。

相关文章： 什么是API（应用程序编程接口）？

JavaDoc标签列表

下面您可以找到流行和有用的JavaDoc标记。

标签	说明	语法
@作者	用于作者或开发人员名称。	@作者姓名文本
{@code}	以代码字体显示文本，而不将文本解释为HTML标记或嵌套的javadoc标记。	{@code text}
{@docRoot}	表示从任何生成的页到生成的文档根目录的相对路径。	{@docRoot}
@已弃用	添加关于给定实体的警告，如类、函数或接口在将来的版本中将是绝对的	@弃用的弃用文本
@例外情况	添加 投掷 生成的文档的副标题，带有类名和描述文本。	@异常类名描述
{@inheritDoc}	从超类继承文档。这对于类继承很有用	从直接上级类继承注释。
{@link}	插入带有可见文本标签的内嵌链接，该标签指向引用类的指定包、类或成员名称的文档。	{@link package.class#成员标签}
{@linkplain}	与{@link}相同，除非链接的标签显示为纯文本而不是代码字体。	{@linkplain package.class#member label}
@参数	向“参数”部分添加具有指定参数名称和指定描述的参数。	@参数名称说明
@返回	添加带有描述文本的“Returns”部分。	@退货说明
@看到了吗	添加一个带有链接或文本条目的“See Also”标题，指向我们可以添加更多解释的引用。	@见参考文献
@序列号	在文档注释中用于默认的可序列化字段。	@序列字段说明|包含|排除
@串行数据	记录由writeObject（）或writeExternal（）方法写入的数据。	@serialData数据描述
@序列域	记录ObjectStreamField组件。	@serialField字段名字段类型字段说明
@自	在生成的文档中添加一个带有指定自始文本的“Since”标题，以设置Java源代码的创建或更改日期。	@自发布以来
@投掷	@throws和@exception标记是同义词。它们可以互换使用。	@抛出类名描述
{@value}	当{@value}在静态字段的doc注释中使用时，它将显示该常量的值。	{@value package.class#field}
@版本	有关应用程序或源代码的版本信息将与此标记一起添加。	@版本文本

相关文章： 什么是API（应用程序编程接口）？

设置作者姓名、版本、发布日期

我们将从一个简单的例子开始，我们将把作者姓名，版本和发行版  Java源代码中的日期文档。

/** * @author      İsmail Baydan * @version     1.0 * @since       2014-01-01 * * */public class HelloWorld{        public static void main(String args[])        {                System.out.println("Hello World!");                String name="Poftut.com";                PrintHello(name);        }        public void PrintHello(String name)        {                System.out.println("Hello " + name);        }}

使用javadoc命令生成文档

我们有一个包含javadoc文档的基本Java源代码。我们将使用命令行 javadoc 命令并提供Java源代码文件名 HelloWorld.java 在这个例子中。

$ javadoc HelloWorld.java

输出提供了有关javadoc创建的详细信息。首先，加载HelloWorld.java源代码文件并解析注释。然后所有与javadoc相关的文档都将生成为 HTML 文件夹。如果有错误或警告，它将在javadoc生成结束时显示。

生成的HTML文档文件将命名为 HelloWorld.html . 它将如下所示。

或者，我们可以通过提供带有如下glob符号的路径或目录来生成多个Java源代码文件文档。

$ javadoc src/*

将生成的文档放入指定目录

默认情况下，使用javadoc命令，生成的文档将放在源代码目录中。我们还可以使用特定的目录来存储文档。我们将使用 -d 提供新的文档路径。在下面的示例中，我们将文档路径设置为 doc .

$ javadoc -d doc src/*

记录Java类

Java类可以使用 @link , @author 标签如下。在下面的示例中，我们将设置类作者名称和类层次结构的链接。

/*** HelloWorld is the main entity we'll be using to . . .* * Please see the {@link com.poftut.javadoc.Person} class for true identity* @author İsmail Baydan* */public class HelloWorld extends Person{   // other fields and methods}

记录Java字段

我们还可以为特定字段和变量创建文档，如下所示。

/** * The name of a person we will salute */String name;

记录Java方法/函数

我们可以用 @param , @return , @see , @since 标签，以便放置一些有关方法或函数的文档。

• `@param`将提供有关参数的信息。我们将在同一行中提供参数名称和参数说明。
• `@return`用于提供函数返回信息。
• `@see用于提供有关函数的一些链接。
• `@因为`用于设置函数的创建或发布日期。

         /**         * @param name The name of the persone we want to salute         *         * @return will return void         *         * @see <a href="https://www.poftut.com">Poftut</a>         *         * @since 1.0         *         */        public void PrintHello(String name)        {                System.out.println("Hello " + name);        }

创建自定义标记

即使Java提供了很多有用的标记，为了记录Java源代码，我们可能需要使用一些额外的或不存在的标记来描述源代码。在javadoc执行期间，我们可以使用以下语法轻松地创建自定义标记，并在Java源代码中使用它。

TAG_NAME:LOCATIONS_ALLOWED:HEADER

• `标记u NAME`是新创建的标记名。
• `LOCATION_ALLOWED`用于设置此标记的使用位置`a意味着无处不在。
• `HEADER`是将在生成的文档中显示此标记内容的标记的类别或标题。

相关文章： 什么是API（应用程序编程接口）？

在下面的示例中，我们将创建一个名为 location 用于设置有关源代码物理位置的信息。

/** * @location Ankara  **/

为了在生成的Java文档中使用custom标记，我们将提供custom标记创建命令作为javadoc命令的参数，如下所示。

$ javadoc -tag location:a:"Locations" HelloWorld.java

使用CSS设置生成文档的样式

打印JavaDoc树结构

在Eclipse中生成JavaDoc