第二章：注释

星宇小C

已于 2023-03-21 12:33:22 修改

阅读量52

点赞数

分类专栏： JavaSE笔记文章标签： java

于 2023-03-10 20:07:26 首次发布

本文链接：https://blog.csdn.net/weixin_55192559/article/details/129432171

版权

JavaSE笔记专栏收录该内容

9 篇文章 0 订阅

订阅专栏

一、单行注释和多行注释

单行注释：适用于对单行语句的注释。（在语句";" 的后面 or 另作一句）

基本格式： // 注释文字

多行注释：适用于对代码块的注释。（描述代码块的作用）

基本格式： /* 注释文字 */

/*  多行注释：
* 1、类名：hello
* 2、方法：main
* 3、功能：输出hello  */
public class hello {
    public static void main(String[] args) {
        // 单行注释：输出hello
        System.out.println("hello");    // 单行注释：输出hello
    }
}

使用细节：

被注释的文字，不会被 JVM（java 虚拟机）解释执行，增强可读性
多行注释里面不允许有多行注释嵌套
非javadoc的注释（代码）给代码的维护者看方面维护及该代码的作用

二、文档注释：javadoc

需求：项目需要给客户使用，让客户能够快速上手的说明书

javadoc是JDK提供的工具，该工具用于解析源文件（源代码）中文档注释，生成网页版的API说明文档。适用于类、方法的注释。

优点：能让对方快速上手项目

缺点：对新手不友好，且进行编注比较难——多练

（一）编写方式

基本格式： /** @标签注释文字 */

在编写好的方法的上方：/** + Enter会由系统自动增加的@标签和句尾 */（也可以自加）

以下是常用的@标签，不是限定在某个场景，还可以在其他场景使用（包、类、接口、方法的上方）

【根据需要自定义】

详细描述

@author（作者名称）、@version（当前版本【可写时间】）、@since （更新版本）、@deprecated（过期版本）

/**
 * @author  ccs
 * @Version v1.0
 * @since v1.5
 * @deprecated（since = 1.0,forRemoval = true）  //since：从什么版本开始弃用，forRemoval：是否会被删除
 */

public class hello { }

{@code 注释文本} （会被解析成<code> 注释文本 </code>）

一般在Javadoc中只要涉及到类名或者方法名、关键字，都需要使用{@code }进行标记

（将html标签，变为普通文本）

/**
 *  If the {@code format} is {@code null}
 */

public PrintStream format(String format, Object ... args) {}

常用html标签：<p>、<a>、<pre>、<ul>、<ol>、<li>、<i> 【在转换为javaDoc文档时，就有html效果】
- <p> 注释文本：段落文本说明，可以不使用结束标签<\p>（相当于写作文的段落前要空两格）
- <a href = "链接地址" > 链接说明 <\a> ：链接地址
- <pre> 注释文本 </pre>：预定义格式化文本，文本通常会保留空格和换行符、呈现为等宽字体。
  - 通常用来表示计算机的源代码部分
  - 注意：标签中如果有小于号、大于号、泛型 在生成javadoc时会报错
  - 解决方法：跟{@code }搭配使用
- <i> 注释文本<\i>：斜体
- <ul> 注释文本<li>：无序列表
- <ol> 注释文本<li>：有序列表

    /**
     * 标题，不用<p>
     *
     * <p>Note: this method returns {@code true} for a {@code CharSequence}
     * <a href="http://commons.apache.org/proper/commons-lang/">Apache's Commons Lang</a>   //表示有个链接地址
     * that purely consists of whitespace.
     *
     *<pre>{@code
     *     int result = identity;
     *     for (int element : this stream)
     *         result = accumulator.applyAsInt(result, element)
     *     return result;
     * }</pre>
     *
     */

方法参数描述

@param 形参名（形参描述，跳转功能）
@return （返回值描述）
{@value 常量 } （常量描述，跳转功能）

    /**
     * sum方法的说明：整型数据的输入输出
     * @param a 形参a，传递整型数据
     * @param b 形参b，传递整型数据
     * @return 返回sum的值
     * {@value sum} 用于a + b 的赋值
     */
    public int sum(int a,int b){
        int sum = 0;
        sum = a + b
        return sum;
    }

@inheritDoc (用于注解在重写方法或者子类上，用于继承父类中的Javadoc)
- 基类的文档注释被继承到了子类
- 子类可以再加入自己的注释（特殊化扩展）
- @return @param @throws 也会被继承

链接跳转描述

Ctrl键+鼠标单击快速跳到相应的类或者方法上

{@link 包名.类名#方法名(参数类型)} 优点：不用顶头；缺点：设定链接，只能单独跳转

{@linkplain....} （纯文本形式，无链接效果）

//不在同个包内时的链接设定
{@link java.lang}                          //跨包指向
{@link java.lang.Demo}                     //跨包指向类
{@link java.lang.Demo#sum(int,int)}        //跨包指向类的方法

//在同个包内时的链接设定
{@link Demo}                               //指向类
{@link Demo#sum(int,int)}                  //跨包指向类的方法
 
//在同个类内时的链接设定，
{@link #sum(int,int)}                      //同个类指向方法，必须有#

// 可以进行多个的设定
{@link String} and {@link StringBuilder}   //and是普通字符

细节：方法都是通用的，只是如何便捷看自己

@see 包名.类名#方法名(参数类型) 优点：设定链接，可以标签多个目的跳转；缺点：必须顶头；

/** 
 * @see demo.unit.one.hello#main(String[]) 普通字符*/    //必须顶头

//点击包，可以跳转到包
//点击类，可以跳转到类
//点击方法，可以跳转到方法

作用：调用方法被篡改了，注释会报红，起到一个提示作用

异常链接描述

@throws 异常类型 （用于描述方法内部可能抛出的异常）
@exception 异常类型 （用于描述方法内部可能抛出的异常）

两个注解同理

    /**
     * @throws IllegalArgumentException
     * @exception IllegalArgumentException
     */

    public boolean createOrder() throws IllegalArgumentException{ }