01 Java注释

注释(comment)

注释是对代码的说明解释，以便于开发者理解代码，提高开发效率，方便代码在以后进行维护。注释只是对开发者起到一个提示作用，因此不被编译执行。Java中包含三种注释：单行注释、多行注释、文档注释

1 Java中的三种注释

单行注释，以 //开头，

// 这是单行注释

多行注释，以/*开头，以*/结尾，中间可以编辑多行注释内容

/*
多行注释
多行注释
*/

文档注释

1）文档注释一般用于说明类、成员变量和方法的功能，以便于通过Javadoc生成代码的API帮助文档。

2）文档注释只放在类、接口、成员变量、方法之前，因为 Javadoc 只处理这些地方的文档注释，而忽略其它地方的文档注释。

/**
 * 这是一段文档注释
 * @Description HelloWord
 * @Author 猿习笔记
 */

3）Javadoc 可识别的标签

标签	描述
@author	作者标识
@deprecated	标识当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API
{@docRoot}	指明当前文档根目录的路径
@exception	标志一个类抛出的异常
{@inheritDoc}	从直接父类继承的注释
{@link}	链接到某个特定的成员对应的文档中
{@linkplain}	插入一个到另一个主题的链接，但是该链接显示纯文本字体
@param	方法的入参名及描述信息，如入参有特别要求，可在此注释
@return	对函数返回值的注释
@see	引用,查看相关内容，如类、方法、变量等
@serial	说明一个序列化属性
@serialData	说明通过writeObject( ) 和 writeExternal( )方法写的数据
@serialField	说明一个ObjectStreamField组件
@since	描述文本,API在什么程序的什么版本后开发支持
@throws	构造函数或方法所会抛出的异常
{@value}	显示常量的值，该常量必须是static属性
@version	版本号

2 使用Javadoc生成 API 帮助文档

我们以下面这段代码为例，用介绍使用cmd命令和IDEA两种方式生成javadoc文档。

/**
 * JavadocTest.java
 * 这是一个用来演示如何使用
 * Javadoc 生成API帮助文档的类
 * @author 猿习笔记
 * @version 1.0
 */
public class JavadocTest{
    /**
     * 对输入的两个整数求和
     * @param a 被加数
     * @param b 加数
     * @return a与b的和
     */
    private int add(int a, int b){
        return a+b;
    }

    /**
     * 打印求和结果
     * @param  a 被加数
     * @param b 加数
     */
    public void showAdd(int a, int b){
        System.out.println( a + "+" + b + "结果为：" + add(a,b));

    }

    /**
     * 主函数
     * @param args ...
     */
    public static void main(String [] args){
        JavadocTest javadocTest = new JavadocTest();
        javadocTest.showAdd(3,9);
    }
}

方式一：使用 cmd 命令生成

// 在源文件所在目录打开 cmd 执行命令 生成 javadoc 文档；生成后 index.html 为文档首页
javadoc -d 文档存放目录 -encoding UTF-8 -charset UTF-8 源文件名.java

常用选项

名称	说明
-public	仅显示 public 类和成员
-protected	显示 protected/public 类和成员（默认值）
-package	显示 package/protected/public 类和成员
-private	显示所有类和成员
-d <directory>	输出文件的目标目录
-version	包含 @version 段
-author	包含 @author 段
-splitindex	将索引分为每个字母对应一个文件
-windowtitle <text>	文档的浏览器窗口标题

• 注：

  ① Javadoc 默认只提取 public、protected 修饰的部分。如果要提取 private 修饰的部分，需要使用 -private 。

  ② 可以通过 javadoc -help 命令查看 javadoc 使用说明。

生成过程：

方式二：使用 IDEA 生成

// IDEA 生成 javadoc 文档；生成后 index.html 为文档首页
Tools → Generate JavaDoc → 选择[Whole prject | File] → output directory → 
Locate(zh_CN) → other cmd (-encoding UTF-8 -charset UTF-8  -windowtitle "API文档1.0") 

生成过程

3 Reference

[1] https://www.cnblogs.com/jddreams/p/14503641.html

[2] http://c.biancheng.net/view/6262.html

[3] https://www.runoob.com/java/java-documentation.html

[4] https://www.bilibili.com/video/BV12J41137hu

关注公众号：猿习笔记，回复 “Java基础笔记” 获取电子版笔记