Java只是三种注释方式。前两种分别是// (单行注释)和/* */(多行注释),第三种被称作说明注释,它以/** 开始,以 */结束。说明注释允许你在程序中嵌入关于程序的信息。你可以使用javadoc工具软件来生成信息,并输出到HTML文件中。
Javadoc可识别的标签如下:
标签 | 描述 | 示例 |
---|---|---|
@author | 标识一个类的作者 | @author description |
@deprecated | 指名一个过期的类或成员 | @deprecated description |
{@docRoot} | 指明当前文档根目录的路径 | Directory Path |
@exception | 标志一个类抛出的异常 | @exception exception-name explanation |
{@inheritDoc} | 从直接父类继承的注释 | Inherits a comment from the immediate surperclass. |
{@link} | 插入一个到另一个主题的链接 | {@link name text} |
{@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 description |
@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 |
示例代码:
/**
* this class describe a student
*
* @author qianqian
* @version 1.0.2
* @see java.lang.String
*/
public class Student {
String name;
int age;
String schoolName;
/**
* this is this class constructor
*
* @param name student's name
* @param age student's age
* @param schoolName student's schoolName
*/
public Student(String name, int age, String schoolName) {
this.name = name;
this.age = age;
this.schoolName = schoolName;
}
/**
* this function was built to get student name
*
* @return this student's name
*/
public String getName() {
return name;
}
/**
* this function was built to set student name
*
* @param name this is student'name
* @throws Exception this is a Exception
*/
public void setName(String name) throws Exception {
this.name = name;
}
}
在IDEA中生成javadoc文档
点击菜单Tools -> Generate JavaDoc
依次选择要导入的类(可以选择整个项目),然后选择文档输出路径,再选择允许导入的权限修饰符和标签,最后点击ok即可,注意,文档最好不要使用中文。
导出完成后,打开导入路径,点击index.html 即可,如下:
javadoc文档将有助于别人很容易的读懂你的代码,即使在日常代码中,也要养成注释详细的习惯
👍!!!👌