何为Javadoc？如何写出格式规范的Javadoc，让我们一起来了解一下吧

附上两个参考的链接。

https://blog.csdn.net/vbirdbest/article/details/80296136

https://www.cnblogs.com/wdh1995/p/7705494.html

一、Javadoc的基本信息：

   javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。javadoc命令是用来生成自己API文档的，使用方式：使用命令行在目标文件所在目录输入javadoc +文件名.java。

  Javadoc主要用于代码的注释规范性，可以写在类上面和方法上面。

二、写在类上面的Javadoc：

    写在类上的文档标注一般分为三段：

• 第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束

     单行示例：

 package org.springframework.util;
/**
 * Miscellaneous {@link String} utility methods.
 * 
 */
public abstract class StringUtils { 

   多行示例：

 package java.lang;
/**
 * Class {@code Object} is the root of the class hierarchy.
 * Every class has {@code Object} as a superclass. All objects,
 * including arrays, implement the methods of this class.
 */
public class Object {}

在注释中出现以@开头的东西就是Javadoc文档标记，是JDK定义好的，如@author、@version、@since、@see、@link、@code、@param、@return、@exception、@throws等。 

1.@link的使用语法{@link 包名.类名#方法名(参数类型)}用于快速链接到相关代码，其中当包名在当前类中已经导入了包名可以省略，可以只是一个类名，也可以是仅仅是一个方法名，也可以是类名.方法名，使用此文档标记的类或者方法，可用通过按住Ctrl键+单击 可以快速跳到相应的类或者方法上，解析成html其实就是使用< code> 包名.类名#方法名(参数类型)< /code>

// 完全限定的类名
{@link java.lang.Character}

// 省略包名
{@link String}

// 省略类名，表示指向当前的某个方法
{@link #length()}

// 包名.类名.方法名(参数类型)
{@link java.lang.String#charAt(int)}

2. {@code text} 会被解析成<code> text </code>，将文本标记为代码样式的文本，在code内部可以使用 < 、> 等不会被解释成html标签, code标签有自己的样式，一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记。

• 第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束

详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用html标签，如<p>、<pre>、<a>、<ul>、<i>等标签， 通常详细描述都以段落p标签开始。

详细描述和概要描述中间通常有一个空行来分割。

 一般段落都用p标签来标记，凡涉及到类名和方法名都用@code标记，凡涉及到组织的，一般用a标签提供出来链接地址。

• 第三段：文档标注，用于标注作者、创建时间、参阅类等信息

 三、写在方法上面的Javadoc：

写在方法上的文档标注一般分为三段：

• 第一段：概要描述，通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束
• 第二段：详细描述，通常用一段或者多段话来详细描述该方法的作用，一般每段话都以英文句号作为结束
• 第三段：文档标注，用于标注参数、返回值、异常、参阅等

方法详细描述上经常使用html标签来，通常都以p标签开始，而且p标签通常都是单标签，不使用结束标签，其中使用最多的就是p标签和pre标签,ul标签, i标签。

pre元素可定义预格式化的文本。被包围在pre元素中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体，pre标签的一个常见应用就是用来表示计算机的源代码。

一般p经常结合pre使用，或者pre结合@code共同使用(推荐@code方式)
一般经常使用pre来举例如何使用方法

注意：pre>标签中如果有小于号、大于号、例如泛型 在生产javadoc时会报错。

四、生成Javadoc：

1、点击eclipse的【Project】菜单，选择【Generate JavaDoc】选项。

2、Next

（1）选择您要生成JavaDoc的工程

（2）选择哪些级别的内容生成JavaDoc，默认为public，如果选择private则会全部内容都生成。

（3）选择doc的生成位置，默认为工程目录下，建议不要修改。

3、继续下一步

（1）勾选Document Title，然后填写文档标题。

（2）点击【Next】按钮

4、继续下一步

（1）选择使用的jdk版本

（2）点击【Finish】按钮

注意这里加上一个：-encoding UTF-8 -charset UTF-8，可以解决 编码GBK的不可映射字符”问题。

 5、可以看到控制台输出生成javadoc的信息。

 6、项目下生成一个【doc】的目录，里面存放着javadoc文档。

 7、打开doc目录，用浏览器打开index.html

 8、最终可以看到一个完整的API文档、javadoc就生成了。