这是我参与8月更文挑战的第26天，活动详情查看：8月更文挑战
前言
注释是一个文件的灵魂，在我们开发中，经常会查阅各种文档，文档上都会有很详细的注释，有的甚至都有示例，那么开发这么久了，你会使用文档注释吗？下面将进行java文档注释的介绍
初始注释
注释作用：主要是用来生成说明文件时，供使用者或者阅读者快速熟悉所设置，也是为自己以后看到能一目了然的作用。
单行注释
- 单行注释：
- 符号【//】
- 格式：// 后面跟上注释内容注释内容
- 示例如下：
//main方法
public static void main(String[] args) {
System.out.println("掘金 - 代码不止，掘金不停");
}
复制代码多行注释
- 多行注释
- 符号【/* */】
- 格式：/* 注释内容 */
- 示例如下：
//main方法
public static void main(String[] args) {
/*
以下执行将输出
【掘金 - 代码不止，掘金不停】
*/
System.out.println("掘金 - 代码不止，掘金不停");
}
复制代码文档注释
- 文档注释
- 符号【/***/】
- 格式：它以 /** 开始，以 */结束。文档注释也是说明注释，允许你在程序中嵌入关于程序的信息。你可以使用 javadoc 工具软件来生成信息，并输出到HTML文件中。
- 示例如下：
/**
* @MethodName: testJavaDoc
* @Description: 测试多行文本输出
* @param
* @Return: void
* @Author: JavaZhan @公众号:Java全栈架构师
* @Date: 2020/6/13
**/
public static void testJavaDoc(){
System.out.println("掘金 - 代码不止，掘金不停");
System.out.println("作者：小阿杰");
System.out.println("主页地址：https://juejin.cn/user/2040300414187416/posts");
System.out.println("欢迎关注交流学习！");
}
复制代码是不是很好奇，@MethodName、@Description、@param、@Return除了文章出现的标签，还有哪些文档注释的标签呢？都是那些标签可以使用呢？下面给大家汇总了一下。
注释常用的标签
| 标签 | 描述 | 示例 |
|---|---|---|
| @Author | 一个类或者方法的的作者 | @author description |
| @Deprecated | 一个过期的类或成员 | @deprecated description |
| @Date | 创建日期 | @Date: 2020/6/13 |
| {@docRoot} | 当前文档根目录的路径 | Directory Path |
| @exception | 抛出的异常 | @exception exception-name explanation |
| {@inheritDoc} | 从直接父类继承的注释 | Inherits a comment from the immediate surperclass. |
| {@link} | 插入一个到另一个主题的链接 | {@link name javadoc} |
| {@linkplain} | 插入一个到另一个主题的链接，但是该链接显示纯文本字体 | Inserts an in-line link to another topic. |
| @param | 方法的参数 | @param parameter-name explanation |
| @return | 返回值类型 | @return explanation |
| @see | 指定一个到另一个主题的链接 | @see anchor |
| @serial | 一个序列化属性 | @serial description |
| @serialData | 说明通过writeObject( ) 和 writeExternal( )方法写的数据 | @serialData |
| @serialField | 说明一个ObjectStreamField组件 | @serialField name type description |
| @since | 标记当引入一个特定的变化时 | @since release |
| @throws | 和 @exception标签一样，抛出异常 | The @throws tag has the same meaning as the @exception tag. |
| {@value} | 显示常量的值，该常量必须是static属性。 | Displays the value of a constant, which must be a static field. |
| @version | 指定类的版本 | @version info |
| @MethodName | 方法名称 | @MethodName testJavaDoc |
在/** 之后，第一行或几行是关于类、变量和方法的主要描述。注释文档可以根据标签为类、方法、接口、枚举等提供便于开发人员和使用人员易阅读的文本内容。
快速开始
生成文档
本次生成文档采用javadoc生成。javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。
javadoc命令是用来生成自己API文档的，使用方式：使用命令行在目标文件所在目录输入javadoc +文件名.java。
命令如下：
javadoc ****.java
复制代码进入目录
如下图，进入将要执行生成的文件，输入：javadoc ****.java
执行javadoc Tests.java，生成如下文件和文件夹。
点击其中index.html，已经进入到文档页面。
结语
以上就是Java 文档注释生成的过程。
作者介绍：【小阿杰】一个爱鼓捣的程序猿，JAVA开发者和爱好者。公众号【Java全栈架构师】维护者，欢迎关注阅读交流。
好了，感谢您的阅读，希望您喜欢，如对您有帮助，欢迎点赞收藏。如有不足之处，欢迎评论指正。下次见。
近期评论