疯狂Java笔记:3.1 注释

来源：互联网发布：淘宝站内推广有哪些编辑：程序博客网时间：2024/06/06 18:25

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{}

在 jwz、jwz1包的上级目录[该例中上级目录为API_Test]打开命令行窗口[cmd][鼠标右击文件夹有该选项]，输入以下命令：javadoc -d apiTest jwz jwz1
注意：源文件的编码字符集为GBK

0 0