Java基础01_注释

注释

Java中的注释有三种：
单行注释
多行注释
文档注释

单行注释

可以注释一行文字；

public class HelloWorld{
    public static void main(String args[]) {
        //单行注释
        //输出一个Hello World
        System.out.println("Hello World!");
    }
}

多行注释

可以注释多行文字；

public class HelloWorld{
    public static void main(String args[]) {
        /*
        多行注释
        输出一个Hello World
         */
        System.out.println("Hello World!");
    }
}
//注意的是 多行注释的不同于文档注释 只需要键盘打出/* 然后回车就可以 不需要打/**回车 因为这个是文档注释

文档注释

文档注释主要是用来生成 java 开发文档 javadoc 的，生成的开发文档和 Java 本身的 API 帮助文档是一样的，也就是对你所写的类进行解释说明，所以它还需要搭配一些文档标记，进行解释说明，而且在文档注释中可以使用 HTML 语言，jdk 源码中有大量的文档注释。文档注释是有功能的 可以加入一些参数 比如描述和作者；

（1）通用的文档标记
以下文档标记在类、方法、变量和常量上都经常使用。

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

（2）类上常用文档标记

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

@author：用来标记作者，如果一段程序是由多个作者来维护，则可以标记多个@author,@author 后面可以跟作者姓名(也可以附带作者邮箱地址)、组织名称(也可以附带组织官网地址)
// 纯文本作者
@author Rod Johnson

// 纯文本作者，邮件
@author Igor Hersht, igorh@ca.ibm.com

// 超链接邮件 纯文本作者
@author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>

// 纯文本邮件
@author shane_curcuru@us.ibm.com

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

// 超链接组织地址 纯文本组织
@author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>

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

@since：表示从以下版本开始有这个类，标记文件创建时项目当时对应的版本，后面可以跟版本号或是时间。
//跟版本号，以下是ArrayList类里的标记，说明从jdk1.2开始就有该类了
/*
* @since 1.2
**/
//跟时间
/**
* @since 20 April 2021
*/

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

（3）方法上常用文档标记

@param：该文档标记后面写方法的参数名，再写参数描述。
/**
* @param str
* the {@code CharSequence} to check (may be {@code null})
*/
public static boolean containsWhitespace(@Nullable CharSequence str) {}


@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 <code>key</code> is null.
*/
public static Object get(String key) throws IllegalArgumentException {}

@see：可用在类与方法上，表示参考的类或方法。
/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}

（4）变量和常量上的文档规范

变量和常量上用的比较多的文档标记是@link和@code，主要注释该常量或变量的基本用法和相关内容。

public class HelloWorld{
    public static void main(String args[]) {
        /**
         * @Description Hello World
         * @Author DL
         * @version 1.0
         */
        System.out.println("Hello World!");
    }
}