《疯狂Java讲义(第3版)》.(李刚)——注释

最新推荐文章于 2023-06-16 04:24:43 发布

AlexLongjiu

最新推荐文章于 2023-06-16 04:24:43 发布

阅读量4.3k

点赞数

分类专栏： java 文章标签： java 注释调试重构

本文链接：https://blog.csdn.net/qq_32347977/article/details/51207128

版权

java 专栏收录该内容

31 篇文章 1 订阅

订阅专栏

本文详细介绍了Java编程中注释的重要性，包括单行、多行和文档注释的使用。重点讲解了Java的文档注释，特别是如何使用Javadoc工具生成API文档，包括javadoc命令的参数、各种Javadoc标记的用法，如@author、@deprecated、@see等，并给出了实际示例。

摘要由CSDN通过智能技术生成

1、注释的必要性：
1）自己或他人重构系统时方便理清楚这段代码的流程和思路。
2）增加自己代码的可读性。
3）当代码出现错误时注释代码可逐渐排查错误，缩小错误范围（我自己更喜欢debug）。
2、注释类型
1）单行注释。
在需要注释的前方加上双斜杠即可（//）

    public class LineComment
{
    //这是单行注释的范例
    public static void main(String args[])
    {
        //这只是一个单行注释的例子
        System.out.println("Single Line Comment");
    }
}

2）多行注释。
在需要注释的前方加上“/*”表示注释开始，结尾加上“*/”表示注释结束。
代码：

    public class MultiCommont
{
    /*
     *这是段注释的一个简单的例子
     *这里是函数入口main方法
     */
    public static void main(String args[])
    {
        System.out.println("Multi Lines Comments");
    }
}

3）文档注释。
文档注释是Java里面的一个比较厉害的功能，它可以用于注释类、属性、方法等说明，而且通过JDK工具javadoc直接生成相关文档，文档注释的基本格式为“/**...*/”，不仅仅如此，文档注释本身还存在语法
javadocTest:包括类、方法、成员变量的注释

package com.alex.demo01;

/**
 * Description
 * <br>网站：<a href= "http://blog.csdn.net/qq_32347977">Alex的博客</a>
 * <br>This is a demo of javadoc
 * <br>
 * <br>
 * <br> 
 * @author Alex
 * @version 1.0
 */
public class JavaDocTest {
    /**
     * 简单测试成员变量
     */
    private String name;
    /**
     * 主方法，程序的入口
     * @param args
     */
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Test类:

package com.alex.demo01;

/**
 * Description
 * <br>网站：<a href= "http://blog.csdn.net/qq_32347977">Alex的博客</a>
 * <br>This is a demo of javadoc
 * <br>
 * <br>
 * <br> 
 * @author Alex
 * @version 1.0
 */
public class Test {

    /**
     * 简单的成员变量
     */
    private int age;

    /**
     * Test的测试构造器
     */
    public Test(){

    }
}

javadoc 命令生产api文档：

javadoc -d *Test.java

参数详解：在windows命令行输入javaodc -help

这里写图片描述

为了生产更详细的api文档，可以使用如下的javadoc标记：

这里写图片描述

[1]文档和文档注释的格式化：
　　生成的文档是HTML格式的，而这些HTML格式的标识符并不是javadoc加的，而是我们在写注释的时候写上去的。因此在格式化文档的时候需要适当地加入HTML标签，例如：

/**
 *This is first line.<br/>
 *This is second line.<br/>
 *This is third line.<br/>
 **/

　　[2]文档注释的三部分：
　　根据在文档中显示的效果，文档注释可以分为三个部分，这里举个例子：

/**
 *testDoc方法的简单描述
 *<p>testDoc方法的详细说明</p>
 *@param testInput String 打印输入的字符串
 *@return 没有任何返回值
 **/
public void testDoc(String testInput)
{
    System.out.println(testInput);
}

　　简述：文档中，对于属性和方法都是现有一个列表，然后才在后面一个一个的详细说明，列表中属性名或者方法名后面那段说明都是简述。
　　
　　特殊说明：除开上边的两部分，最后一个部分就是特殊说明部分，特殊说明部分使用JavaDoc标记进行，这些都是JavaDoc工具能够解析的特殊标记，这一点下边章节将会讲到
　　
　　[3]使用javadoc标记：
　　
　　javadoc标记是java插入文档注释中的特殊标记，它们用于识别代码中的特殊引用。javadoc标记由“@”以及其后跟着的标记类型和专用注释引用组成。它的格式包含了三个部分：
　　
　　@、标记类型、专用注释引用

　　有时候我们也可以直接理解为两个方面：@和标记类型、专用注释引用；Javadoc工具可以解析Java文档注释中嵌入的特殊标记，这些文档标记可以帮助自动从源代码生成完整的格式化API，标记用“@”符号开头，区分大小写，必须按照正确的大小写字母输入。标记必须从一行的开头开始，否则会被视为普通文本，而且按照规定应将相同名字的标记放一起，比如所有的@see标记应该放到一起，接下来看一看每一种标记的含义。
　　
　　@author(1.0)：语法[@author name-text]
　　
　　当使用-author选项的时候，用指定的name-text在生成文档的时候添加“Author”项，文档注释可以包含多个@author标记，可以对每个@author指定一个或者多个名字。
　　@deprecated(1.0)：语法[@deprecated deprecated-text]
　　添加注释，只是不应该再使用该API（尽管是可用的），Javadoc工具会将deprecated-text移动到描述前面，用斜体显示，并且在它前边添加粗体警告：“不鼓励使用”。deprecated-text的首句至少应该告诉用户什么时候开始不鼓励使用该API以及使用什么替代它。Javadoc仅将首句复制到概览部分和索引中，后面的语句还可解释为什么不鼓励使用，应该还包括一个指向替代API的{@link}标记【1.2版本用法】
对于Javadoc 1.2，使用{@link}标记，这将在需要的地方创建内嵌链接，如：

/**
 *@deprecated 在JDK X.X中，被{@link #methodName(paramList)}取代
 **/

【*：在上边的标记里面X.X指代JDK的版本，后边的链接链接的是方法的签名，methodName为方法名，paramList为参数列表】
对于Javadoc 1.1，标准格式是为每个@deprecated标记创建@see标记（它不可内嵌）
　　

@exception(1.0)：语法[@exception class-name description]
　　@throws(1.2)：语法[@throws class-name description]

　　以上两个标记是同义词，用class-name和description文本给生成的文档添加“抛出”子标题，其中class-name是该方法可抛出的异常名。
　　
　　{@link}(1.2)：语法[{@link name label}]
　　
　　出入指向指定name的内嵌链接，该标记中name和label的语法与@see标记完全相同，如下所述，但是产生的内嵌链接而不是在“参见”部分防止链接。该标记用花括号开始并用花括号结束，以使它区别于其他内嵌文本，如果需要在标签内使用“}”，直接使用HTML的实体表示法：
　　

@param(1.0)：语法[@param parameter-name description]

　　
　　给“参见”部分添加参数，描述可以继续到下一行进行操作，主要是提供了一些参数的格式以及描述
　　

　@return(1.0)：语法[@return description]

　　用description本文添加“返回”部分，该文本应描述值的返回类型和容许范围
　　
　　@see(1.0)：语法[@see reference]
　　
　　该标记是一个相对复杂的标记，添加“参见”标题，其中有指向reference的链接或者文本项，文档注释可包含任意数目的@see标记，它们都分组在相同的标题下，@see有三种格式：
@see “string” 注：该形式在JDK 1.2中没有用，它不打印引用文本
为string添加文本项，不产生链接，string是通过该URL不可用的书籍或者其他信息引用，Javadoc通过查找第一个字符为双引号（”）的情形来区分它前边的情况，比如：
@see “这是Java教材，主要是提供给初学者”
上边的注释将会生成：
参见：
　　“这是Java教材，主要是提供给初学者”

@see <a href="page.html#section">Java某章节</a>

添加URL#value定义的链接，其中URL#value是相对URL或者绝对URL，JavaDoc工具通过查找第一个字符小写符号（<）区分它与其他情况，比如：

@see <a href="page.html#section">测试规范</a>

上边的注释将会生成：
参见：
　　测试规范
@see package.class#member label【比较常用的一种格式】
添加带可见文本label的链接，它指向Java语言中指定名字的文档。其中label是可选的，如果省略，则名字作为可见文本出现，而且嵌在HTML标记中，当想要缩写可见文本或不同于名字的可见文本的时候，可以使用label。 ——package.class#member是Java语言中的任何有效名字——包名、类名、接口名、构造函数名、方法名或域名——除了用hash字符(#)取代成员名前面的点之外，如果该名字位于带文档的类中，则Javadoc将自动创建到它的链接，要创建到外部的引用链接，可使用-link选项，使用另外两种@see形式中的任何一种引用不属于引用类的名字的文档。 ——label是可选文本，它是链接的可见标签，label可包含空白，如果省略label，则将显示package.class.member，并相对于当前类和包适当缩短 ——空格是package.class#member和label之间的分界符，括号内的空格不表示标签的开始，因此在方法各参数之间可使用空格 @see package.class#member的典型形式引用当前类的成员

@see #field
@see #method(Type,Type,...)
@see #method(Type argname,Type argname,...)

引用当前包或导入包中的其他类

@see Class#field
@see Class#method(Type,Type,...)
@see Class#method(Type argname,Type argname,...)
@see Class

引用其他包（全限定）

@see package.Class#field
@see package.Class#method(Type,Type,...)
@see package.Class#method(Type argname,Type argname,...)
@see package.Class

@see package简单说明一下：
——第一套形式（没有类和包）将导致 Javadoc 仅搜索当前类层次。它将查找当前类或接口、其父类或超接口、或其包含类或接口的成员。它不会搜索当前包的其余部分或其他包（搜索步骤 4-5）。
——如果任何方法或构造函数输入为不带括号的名字，例如 getValue，且如果没有具有相同名字的域，则 Javadoc 将正确创建到它的链接，但是将显示警告信息，提示添加括号和参数。如果该方法被重载，则 Javadoc 将链接到它搜索到的第一个未指定方法。
——对于所有形式，内部类必须指定为 outer.inner，而不是简单的 inner。
——如上所述，hash 字符（#）而不是点（.）用于分隔类和成员。这使 Javadoc 可正确解析，因为点还用于分隔类、内部类、包和子包。当 hash 字符（#）是第一个字符时，它是绝对不可少的。但是，在其他情况下，Javadoc 通常不严格，并允许在不产生歧义时使用点号，但是它将显示警告。
　　@see标记的搜索次序——JavaDoc将处理出现在源文件（.java）、包文件（package.html）或概述文件（overview.html）中的@see标记，在后两种文件中，必须完全限定使用@see提供的名字，在源文件中，可指定全限定或部分限定的名字，@see的搜索顺序为：
当前类或接口
任何包含类和接口，先搜索最近的
任何父类和超接口，先搜索最近的
当前包
任何导入包、类和接口，按导入语句的次序搜索
　　@since(1.1)：语法[@since since-text]
　　用since-text指定的内容给生成文档添加“Since”标题，该文本没有特殊内部结构，该标记表示该改变或功能自since-text所指定的软件件版本后就存在了，例如：@since JDK 1.4
　　@serial(1.2)：语法[@serial field-description]
　　用于缺省的可序列化域的文档注释中，可选的field-description增强了文档注释对域的描述能力，该组合描述必须解释该域的意义并列出可接受值，如果有需要描述可以多行，应该对自Serializable类的最初版本之后添加的每个可序列化的域添加@since标记。
　　@serialField(1.2)：语法[@serialField field-name field-type field-description]
　　简历Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档，应该对每个ObjectStreamField使用一个@serialField标记
　　@serialData(1.2)：语法[@serialData data-description]
　　data-description建立数据（尤其是writeObject方法所写入的可选数据和Externalizable.writeExternal方法写入的全部数据）序列和类型的文档，@serialData标记可用于writeObject、readObject、writeExternal和readExternal方法的文档注释中
　　@version(1.0)：语法[@version version-text]
　　当使用-version选项时用version-text指定的内容给生成文档添加“版本”子标题，该文本没有特殊内部结构，文档注释最多只能包含一个@version标记。
　　{@code}(1.5)：语法[{@code text}]
　　该标签等同于{@literal}，里面可以直接过滤掉HTML的标签，可以不用<和>来显示（<和>），在这个代码块里面的text部分，可以直接书写代码，即使使用了Hello，在HTML里面也不会识别成为加粗的Hello，而还是原来的代码段Hello的格式输出
　　{@docRoot}(1.3)：语法[{@docRoot}]
　　代表相对路径生成的文件的（目标）的根从任何产生的网页目录，当您要包括如版权页或公司徽标文件的时候它是有用的，你要引用所生成的网页，链接从每个页面底部的版权页面是常见的。（@docRoot将标记可用于在命令行，并在两个文档注释：这个标记是有效的，在所有文档注释：概述、包装类、接口、构造、方法和领域，包括任何标记文本的一部分（如@return ，@param和@deprecated的使用）。
　　比如：

/** 
 * See the <a href="{@docRoot}/copyright.html">Copyright</a>. 
 **/

　　{@inheritDoc}(1.4)：语法[{@inheritDoc}]
　　继承（拷贝）文档从最近的“继承类或可执行的接口”到当前在这个标签的位置的文档注释内容，这使您可以编写更多与继承相关的一般性文档
　　下边的情况比较适合：
在一个方法的主要描述块，在这种情况下，主要描述是整个继承树结构里面的类和接口的一个拷贝。
在文本参数返回的@return @param和@throws等方法标记，在这种情况下，文本标记是整个层次结构里面标签的拷贝。
　　{@linkplain}(1.4)：语法[{@linkplain package.class#member label}]
　　和{@link}类似，除非链接的label是用普通文本的格式显示的，当文本是普通文本的时候该标签就能够起作用，例如：

Refer to {@linkplain add() the overridden method}

　　这个会显示成：
Refer to the overridden method
　　{@value}(1.4)：语法[{@value package.class#field}]
　　主要用来显示静态字段的值：

/**
 * The value of this constant is {@value}
 **/
public static final String SCRIPT_START = "script";

　　[4]JavaDoc标记的举例：
　　——[$]一个使用JavaDoc标记的例子——

/**
 * @author Lang Yu
 * @version 1.2
 */
public class JavaDocBasic {
    /**
     * @see "Main Function JavaDoc"
     * @since JDK 1.4
     * @param args The params of console
     **/
    public static void main(String args[]){
        System.out.println("Hello World!");
    }
}

　　例如有这样一小段代码，在我机器上我放在了D:\Source\work下，然后进入该目录下，使用下边的命令：

D:\Source\work>javadoc -d doc JavaDocBasic.java

　　通过这样的命令使用，在执行该命令了过后电脑上有下边这样的输出，而且去目录下边可以看到一个doc文件夹，用浏览器打开里面的index.html就可以看到生成的文档的内容：
　　

Loading source file JavaDocBasic.java...
Constructing Javadoc information...
Standard Doclet version 1.6.0_16
Building tree for all the packages and classes...
Generating doc\JavaDocBasic.html...
Generating doc\package-frame.html...
Generating doc\package-summary.html...
Generating doc\package-tree.html...
Generating doc\constant-values.html...
Building index for all the packages and classes...
Generating doc\overview-tree.html...
Generating doc\index-all.html...
Generating doc\deprecated-list.html...
Building index for all classes...
Generating doc\allclasses-frame.html...
Generating doc\allclasses-noframe.html...
Generating doc\index.html...
Generating doc\help-doc.html...
Generating doc\stylesheet.css...

　　——[$]一个使用{@link}的例子——

/**
 * @author Lang Yu
 * @see java.lang.String
 */
public class JavaDocLink {
    private int a;
    private int b;
    /**
     * {@link #getAdd() getAdd()} Method
     * @return the result of (a + b)
     **/
    public int getAdd(){
        return a + b;
    }
}

借鉴：http://my.oschina.net/u/141149/blog/283363

AlexLongjiu

关注

0
点赞
踩
2

收藏

觉得还不错? 一键收藏
0
评论
《疯狂Java讲义(第3版)》.(李刚)——注释

1、注释的必要性： 1）自己或他人重构系统时方便理清楚这段代码的流程和思路。 2）增加自己代码的可读性。 3）当代码出现错误时注释代码可逐渐排查错误，缩小错误范围（我自己更喜欢debug）。 2、注释类型 1）单行注释。在需要注释的前方加上双斜杠即可（//） public class LineComment{ //这是单行注释的范例 public sta
复制链接

扫一扫