javadoc的概念及其基本使用

2019/11/07

一、javadoc的概念

javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了。

Javadoc的作用是针对整个方法或者整个类做一个简要的概述的，使得别人不通过看具体方法代码就能知道某个方法或者某个类的作用和功能。写了Javadoc的在别人使用到类时，将鼠标悬停到类上或者方法上，javadoc会以提示信息显示出来，这样开发者在跳进源代码中就能知道类或者方法的作用。

javadoc命令是用来生成自己API文档的，使用方式：使用命令行在目标文件所在目录输入javadoc +文件名.java。

二、javadoc的常用标记

标签	说明
@author	作者标识
@version	版本号
@return	对函数返回值的描述
@deprecated	标识过期API（为了保证兼容性，仍可用，但不推荐用）
@throws	构造函数或方法会抛出的异常
@exception	同@throws
@see	引用，查看相关的内容，如类，方法，变量等，必须顶头写
{@link 包.类#成员}	引用，同@see，但可写在任意位置
{@value}	对常量注释，如果其值包含在文档中，通过改标签引用常量的值
{@code}} {@code text}	将文本标记为code，会被解析成 text } ,在Javadoc成只要涉及到类名或者方法名，都需要使用@code进行标记
@param	说明方法的参数
@inheritDoc	用于继承父类中的Javadoc，父类的文档注释，被继承到了子类

此外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}等标签。

三、文档注释规范

（一）、 Java文档

1. // 注释一行
2. / * */ 注释若干行
3. /** ……*/ 注释若干行，写入Javadoc文档

（二）、文档格式
1.写在类上的文档标注一般分为三段：
第一段：概要描述，通常用一句话或者一段话简要描述该类的作用，以英文句号结束。
单行示例:

多行示例：

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

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

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

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

参考文献

1.https://blog.****.net/vbirdbest/article/details/80296136
2.https://blog.****.net/linton1/article/details/93733508
3.百度词条。