Java 快速入门 知识精简（2）基础知识-注释

注释

1）提高了代码的阅读性，调试程序的重要方法

2）将自己的思想通过注释先整理出来，再用代码去实现

单行注释：

        // 注释内容

多行注释：

        /*

        多行注释不可以嵌套使用

        */

文档注释：

        /**

        * @author 指定作者

        * @version 指定文件的版本

        * @param 参数名 对参数进行说明

        * @return 返回值 对返回值进行说明

        */

说明：

1）注释内容可以被JDK提供的工具javac 所解析生成一套以网页形式存体现的该程序的说明文档。

2）使用文档注释来注释整个类或整个方法

命令行操作：javadoc -d mydocName -author -version -param -return DemoName.java

javadoc -encoding UTF-8 -charset UTF-8 DemoName.java

示例

/**
* ClassName: ${NAME}
* Package: ${PACKAGE_NAME}
* Description: 描述信息
* @Author 作者
* @Create ${DATE} ${TIME}
* @Version 1.0
*/

更多文档标记方式

@link： 用于快速链接到相关代码，使用格式：{@link 包名.类名#方法名(参数类型)}

// 完全限定的类名
{@link java.util.Collections}

// 省略包名，只写类名
{@link String}

// 省略类名，表示指向当前的某一个方法
{@link #toString()}

// 完全限定方法名，包名.类名.方法名(参数类型)
{@link java.lang.String#charAt(int)}




@code： 将文本标记为代码样式文本，一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记，使用格式：{@code text}，其会被解析为 text

//标记类名
{@code ArrayList}

//标记方法名
{@code isEmpty}

//标记某个代码关键字
{@code null}




@param：标记参数    如果一个类支持泛型时，可以通过@param来解释泛型的类型
/**
*@param  the type of elements in this list
*/



@author：标记作者    如果一段程序是由多个作者来维护，则可以标记多个@author

// 纯文本作者
@author Rod Johnson

// 纯文本作者，邮件
@author Igor Hersht, [email protected]

// 纯文本作者，超链接邮件 
@author Ovidiu Predescu

// 纯文本邮件
@author [email protected]

// 纯文本 组织
@author Apache Software Foundation

// 超链接组织地址 纯文本组织
@author  Apache Jakarta Turbine



@version：用于标记当前类版本，默认为1.0
/**
* @version 1.0
*/



@see :另请参阅的意思，一般用于标记与本类相关联的类，该标注可以用在类或方法上。
/**
* @see IntStream
* @see LongStream
* @see DoubleStream
* @see java.util.stream
* /



@return：该文档标记后面写返回值得描述。
/**
* @return {@code true} if the {@code String} is not {@code null}, its
*/
public static boolean hasText(@Nullable String str){}



@throws：该文档标记后面写异常的类型和异常的描述，用于描述该方法可能抛出的异常。
/**
* @throws IllegalArgumentException when the given source contains invalid encoded sequences
*/
public static String uriDecode(String source, Charset charset){}



@exception：该标注用于描述方法签名throws对应的异常。
/**
* @exception IllegalArgumentException if key is null.
*/
public static Object get(String key) throws IllegalArgumentException {}