Java注释

Java 注释

Overview

随着写的程序越来越多,越来越感觉到了 各种注释 越来越重要, 每当我看到一个类库的方法没有方法注释的话,那样这就让我光想骂娘。 作为一个英语学渣+没有一个很大的脑洞,我很难从方法的名字猜到,这个方法的作用。

所以在这里,就想将Java的注释的写法总结一下。

注释种类

//code description
//这是一个单行的注释,一般用来描述一些关键的代码

/*
这是一个多行的注释
多行
多行
好多行
*/
//多行注释 用于注释大段的描述


/*
下面是一个方法的注释

请注意区别方法注释和多行注释
方法注释的开头是 一个斜杠+两个星号
**/

/**
 * 这是一个静态的方法
 *
 * @param arg1 这是一个int类型的参数
 * @param arg2 这是一个String类型的变量
 *
 * @return 返回值的描述
 */
public static int test(int arg1, String arg2) {
    return 0;
}

方法注释

@param

在方法注释中使用 @param [注释名称] 标识参数,在生成注释文档或者在IDE中查看方法说明的时候,那么通过 @param 标识的参数将会生成对应的注释参数。
2018-09-25_14-58-20

/**
 * 这是一个方法
 *
 * @param arg1 参数的描述
 * @param arg2 参数的描述
 */
public static int test(int arg1, String arg2) {
    return 0;
}

@return

@return 用来标识返回值。

2018-09-25_15-01-10

/**
 * 这是一个方法
 *
 * @param arg1 参数的描述
 * @param arg2 参数的描述
 *
 * @return 这是一个返回值
 */
public static int test(int arg1, String arg2) {
    return 0;
}

@throws

@throws 标识方法中可能会抛出的异常。

2018-09-25_15-06-00

/**
 * 这是一个方法
 *
 * @param arg1 参数的描述
 * @param arg2 参数的描述
 * @return 这是一个返回值
 * @throws IllegalArgumentException 异常信息的描述
 */
public static int test(int arg1, String arg2) {
    if (arg1 < 0) {
        throw new IllegalArgumentException("arg1 must be more than 0!");
    }
    return 0;
}

@author

@author 用来标识作者,但是不管是在,生成的代码文档中还有IDE的查看方法的注释,也没有找到生成的Author信息。

@version

@Version 标识版本,..同样没有找到在哪里 :joy:

@see

@see 标识一个参考。

2018-09-25_15-54-26

/**
 * 这是一个方法
 *
 * @param arg1 参数的描述
 * @param arg2 参数的描述
 * @return 这是一个返回值
 * @throws IllegalArgumentException 异常信息的描述
 * @see Program#test2()
 */
public static int test(int arg1, String arg2) {
    if (arg1 < 0) {
        throw new IllegalArgumentException("arg1 must be more than 0!");
    }
    return 0;
}

public static int test2() {
    return 0;
}
@see 的写法
//如果引用了一个类中的方法的话,那么些可以简写如下
//#方法名 比如 #test2()

//如果是不在一个类中的话,写法如下
//类名#方法名 比如 Program#test2()

@depression

@depression 标识,用来当一个方法或者类已经是被弃用了的话,通过这个标识的注释,来提醒用户调用新的方法或者类。

2018-09-25_16-05-40

/**
 * 这是一个方法
 *
 * @param arg1 参数的描述
 * @param arg2 参数的描述
 * @return 这是一个返回值
 * @deprecated 该方法已经弃用,请使用 test2() 方法
 */
@Deprecated
public static int test(int arg1, String arg2) {
    if (arg1 < 0) {
        throw new IllegalArgumentException("arg1 must be more than 0!");
    }
    return 0;
}

HTML代码

因为我们写的Java注释,最后会通过 javaDoc工具来生成HTML格式的文档,而为了更好的显示效果和阅读体验,所以Java的注释中是支持HTML代码的。

2018-09-25_16-19-04

/**
 * <p>这是一个段落</p>
 * <strong>粗体显示</strong>
 *
 * @param arg1 参数的描述
 * @param arg2 参数的描述
 * @return 这是一个返回值
 * @deprecated 该方法已经弃用,请使用 test2() 方法
 */
@Deprecated
public static int test(int arg1, String arg2) {
    if (arg1 < 0) {
        throw new IllegalArgumentException("arg1 must be more than 0!");
    }
    return 0;
}

IntelliJ IDEA 生成 注释文档

2018-09-25_16-20-49

根据需要填写一些需要的配置

2018-09-25_16-21-13

Last modification:September 25th, 2018 at 05:27 pm
If you think my article is useful to you, please feel free to appreciate

Leave a Comment