疯狂Java笔记:3.1 注释

最新推荐文章于 2025-11-27 17:11:16 发布

原创最新推荐文章于 2025-11-27 17:11:16 发布 · 534 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#java

JavaSE教程专栏收录该内容

10 篇文章

订阅专栏

本文介绍Java中的注释类型及用途，特别是文档注释如何使用javadoc工具生成API文档，包括单行、多行注释及文档注释的详细说明。

3.1 注释

用于说明某段代码的作用，某个类的用途，某个方法的功能以及该方法的参数和返回值的数据类型及意义
作用：
- 再次阅读代码时能找回当初的思路
- 程序的可读性取代执行效率成为第一考虑的要素，便于团队成员沟通
- 代码即文档。规范的程序源代码是程序文档的重要组成成分，注释占到源代码1/3

3.1.1 单行注释和多行注释

/**
 * 文档注释
 * @author 梦无涯
 * @version 1.0
 */
public class HelloWorld{
    // 单行注释
    public static void main(String args[]){
        /*
          区域注释
          注释可用于调试程序，缩小错误范围，有利于排错
          System.out.println("这行代码被注释了，不会被执行");
        */
    }
}

3.1.2 文档注释

开发者可以通过JDK提供的javadoc工具将源文件里的文档注释提取生成系统API。其他开发者可以通过调用应用程序接口[API] 编程
API:程序的说明文档，说明类，接口，方法，成员变量，构造器，内部类的功能及用法。
传送门：JDK6 中文版API
传送门：JDK8 英文版API
javadoc 工具默认只处理源文件在public、protected修饰的类、接口、方法、成员变量、构造器、内部类之前的文档注释，忽略其他地方的文档注释。
javadoc 标记：
- @author:指定 Java程序的作者
- @version:指定源文件的版本
- @deprecated:不推荐使用的方法
- @param/@return:方法的参数/返回值的说明信息
- @see：”参见”，用于指定交叉参考的内容
- @exception/@throws:抛出的异常的类型
javadoc 标记使用位置的限制：
- 类/接口：@see/@deprecated/@author/@version
- 方法/构造器:@see/@deprecated/@param/@return/@exception/@throws
- 成员变量:@see/@deprecated

提取文档注释的cmd命令：javadoc -Option ClassName.java/package[类文件名.java/包名]

Option:
    -d <dir>:指定一个路径，用于将生成的API文档放到该指定目录
    -windowtitle <text>:指定一个字符串，用于设置API文档的浏览器窗口标题
    -doctitle <html-code>:指定一个HTML格式的文本，用于指定概述页面的标题
    -header <html-code>:指定一个HTML格式的文本，包含每个页面的页眉
    -version -author -private:提取文档注释中的这三个javadoc标记[默认不提取]

示例：
javadoc -d apiTest -windowtitle 窗口标题 -doctitle 概述页面标题 -header 页眉 -version   -pirvate -author HelloWorld.java // [测试javadoc命令所有选项]
javadoc -d apiTest jwz jwz1 // [提取该路径下的两个package，jwz和jwz1]
javadoc -d apiTest *.java // [ 通配符* 代表当前路径下所有.java文件]

注意：API 的包注释并不是直接放在源文件中，而是必须通过一个包描述文件[标准 HTML文件]另外指定。

包描述文件通常名为package.html，并与该包下所有 Java 源文件放在一起
以下示例几乎涵盖了所有javadoc标记及其使用限制位置，读者可参照着尽可能多的尝试文档注释相关的内容，熟悉javadoc命令的用法，完成单个类，多个类，具有包结构的文档注释的提取

提取包层次结构的文档注释的步骤示例：

编辑源文件 HelloWorld.java 如下：

package jwz;
/**
* Description:
* <br>文档注释 测试类
* <br>本类是完整的Java类示例
* @author 1595486364@qq.com
* @version 1.0
*/
public class HelloWorld{
   /**
    * 这是public成员变量的文档注释，默认被提取
    * @deprecated 该变量已过时
    * @see 私有成员变量name1
    */
   public String name;

   /**
    * 这是私有成员变量的文档注释，必须在javadoc提取时指定 -private选项才能被提取
    */
   private String name1;

   /**
    * 构造器
    * @return 构造器没有返回值，通过new关键字调用构造器并返回初始化的对象
    */
   public HelloWorld(){
       name="小傻逼";
       try{
           System.out.println(hello(name));
       }catch(Exception e){
           System.out.println("异常了");
       }
   }

   /**
    * 这是一个向人打招呼的方法
    * @param  name      对方的名字
    * @return String    该方法返回打招呼的字符串
    * @throws Exception 这是该方法可能抛出的异常
    * @deprecated 该方法已经不推荐使用
    * @see main方法
    */
   public String hello(String name) throws Exception{
       return name+",你好!";
   }

   /**
    * 主方法,程序的入口，JVM从此处开始执行本程序
    * @param args[] 这是主方法的默认参数
    */
   public static void main(String args[]){
       System.out.println("Hello World!");
       new HelloWorld();
       //System.out.println("该行被注释掉了，不会被编译、执行!");
   }
}

将 HelloWorld.java 保存在任意路径 ..\jwz 文件夹下，并编写 jwz包的包描述文件 package.html [新建文本文档，改后缀名为html即可]如下：

<!DOCTYPE html>
<html>
   <head>
       <title>jwz的包描述文件</title>
   </head>
   <body>
       jwz的包描述文件
   </body>
</html>

保存 package.html 到上述 jwz 文件夹下，包描述文件的目录结构如下：

重复上述步骤建立第二个包 jwz1,并增加SimpleClass.java和package.html

package jwz1;
/**
* [@description]最简单的Java类
* @deprecated [@deprecated]该类是Java最简单的类--空类，已过时
* @see [@see]完整的Java类--HelloWorld.java
* @author [@author]jwz,1595486364@qq.com
* @version 1.0[@version]
*/
public class SimpleCalss{

}