Javadoc标签和Javadoc注释规范说明

2023-07-05 17:43:03 70

最近看源码，一些Javadoc常见的注释整理下

Javadoc是Sun公司提供的一个技术，从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。

Javadoc命令是用来生成自己的API文档，使用方式：

javadoc源文件名.java

javadoc-d文档存放目录源文件名.java

通过IDEA生成Javadoc：Tools->GenerateJavaDoc

javadoc标签

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

javadoc注释规范

一、Java文档

//注释一行
/**/注释若干行
/**……*/注释若干行，写入Javadoc文档

二、文档格式

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

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

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

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

生成文档是HTML格式。
换行

分段(写在段前）)

示例

/**
*show方法的简述.
*show方法的详细说明第一行

*show方法的详细说明第二行
*@parambtrue表示显示，false表示隐藏
*@return没有返回值
*/
publicvoidshow(booleanb){
frame.show(b);
}

补充：Java的三种注释Javadoc标记*

三种注释方法：

1、单行注释//注释的内容

2、多行注释/*......*/

3、/**......*/，这种方式和第二种方式相似。这种格式是为了便于javadoc程序自动生成文档。

下面介绍一下Javadoc的标记：

JavaDoc标记

解释

@version

指定版本信息

@since

指定最早出现在哪个版本

@author

指定作者

@see

生成参考其他的JavaDoc文档的连接

@link

生成参考其他的JavaDoc文档，它和@see标记的区别在于，@link标记能够嵌入到注释语句中，为注释语句中的特殊词汇生成连接。eg.{@linkHello}

@deprecated

用来注明被注释的类、变量或方法已经不提倡使用，在将来的版本中有可能被废弃

@param

描述方法的参数

@return

描述方法的返回值

@throws

描述方法抛出的异常，指明抛出异常的条件

特别声明：

（1）javadoc针对public类生成注释文档

（2）javadoc只能在public、protected修饰的方法或者属性之上

（3）javadoc注释的格式化：前导*号和HTML标签

（4）javadoc注释要仅靠在类、属性、方法之前

下面主要举例说明第三种注释的应用：

（1）首先编写.java文件

（2）在命令行中执行以下dos命令：

javadoc*.java//根据相应的Java源代码及其说明语句生成HTML文档

//javadoc标记：是@开头的，对javadoc而言，特殊的标记。

（3）在当前目录下就会产生doc文件夹，里面有一系列的.html文件

附上代码：

*/
/**javadoc注释的内容
*/
publicclassHello{
/**属性上的注释*/
publicStringname;
/**这是main方法,是程序的入口
*@paramargs用户输入参数
*/
publicstaticvoidmain(String[]args){
System.out.println("HelloWorld!");
f1();
}
/**这是第1个方法,其作用是...*/
publicstaticvoidf1(){
System.out.println("f1()！");
}
}

importjava.io.IOException;
/**javadoc注释内容
*@since1.0
*@version1.1
*@authorBlueJey
*
链接到另一个文档{@linkHello},就这些
*seeHello
*/
publicclassHelloWorld{
/**非public，protected属性上的注释不生成*/
publicStringname;
/**这是main方法，是程序的入口
*@paramargs用户输入的参数，是数组
*@throwsIOExceptionmain方法io异常
*/
publicstaticvoidmain(Stringargs[])throwsIOException{
System.out.println("helloWorld!");

f1();
f2(1);
}
/**这是第一个方法，其作用是....
*@deprecated从版本1.2开始，不再建议使用此方法
*/
publicstaticvoidf1(){
System.out.println("fl()!");
}
/**这是第二个方法，其作用是....
*@return返回是否OK
*@parami输入参数i
*@seeHello
*@throwsIOExceptionio异常
*/
publicstaticStringf2(inti)throwsIOException{
System.out.println("f1()!");
return"OK";
}
}

注意：

如果源文件中有用到@version,@author标记，则在执行javadoc命令时，要加-version-author

javadoc-version-author-ddoc*.java

（其中用-version用于提取源文件中的版本信息-author用于提取源文件中的作者信息）

以上为个人经验，希望能给大家一个参考，也希望大家多多支持毛票票。如有错误或未考虑完全的地方，望不吝赐教。

声明：本文内容来源于网络，版权归原作者所有，内容由互联网用户自发贡献自行上传，本网站不拥有所有权，未作人工编辑处理，也不承担相关法律责任。如果您发现有涉嫌版权的内容，欢迎发送邮件至：czq8825#qq.com（发邮件时，请将#更换为@）进行举报，并提供相关证据，一经查实，本站将立刻删除涉嫌侵权内容。