【2023】Kotlin教程第一篇 Kotlin基础第4章 Kotlin语法基础 4.3 注释

悠悠 2024-03-24 10:28 19阅读 0赞

### 【2023】Kotlin教程 ###

#### 文章目录 ####

*   *  【2023】Kotlin教程
     *   *  第一篇 Kotlin基础
         *  第4章 Kotlin语法基础
         *   *  4.3 注释
             *   *  4.3.1 单行注释
                 *  4.3.2 多行注释
                 *  4.3.3 文档注释

![在这里插入图片描述][34a7bc8fb0ba4438bd95f757f9ec7375.png_pic_center]

#### 第一篇 Kotlin基础 ####

#### 第4章 Kotlin语法基础 ####

##### 4.3 注释 #####

Kotlin程序有3类注释：单行注释（//）、多行注释（/\*…\*/）和文档注释（/\*\*…\*/）。注释方法与Java语言都类似

###### 4.3.1 单行注释 ######

单行注释可以注释整行或者一行中的一部分，一般不用于连续多行的注释文本；当然，它也可以用来注释连续多行的代码段。

if (x > 1)  {
        
    // 注释1
    } else {
        
    // 注释2
    }
    
    // if (x > 1)  {
        
    //    // 注释1
    // } else {
        
    //    // 注释2
    // }

在IntelliJ IDEA中对连续多行的注释文本可以使用快捷键：选择多行然后按住“Ctrl+ 斜杠”组合键进行注释。去掉注释也是按住“Ctrl+ 斜杠”组合键。

###### 4.3.2 多行注释 ######

一般用于连续多行的注释文本，但也可以对单行进行注释。Kotlin块注释可以嵌套【Java 不行】

if (x > 1) {
        
        /* 注释1 */
    } else {
        
        /* 注释2 */
    }
    
    /*
    if (x > 1) {
    
    } else {
    
    }
    */
    
    /*
    if (x > 1)  {
    /* 注释1 */       ①
    } else {
        
    /* 注释2 */       ②
    }
    */

在IntelliJ IDEA中添加块注释可以快捷键是“Ctrl+Shift+斜杠”组合键，相反操作去掉块注释也是按住“Ctrl+Shift+斜杠”组合键。

在程序代码中，对容易引起误解的代码进行注释是必要的，但应避免对已清晰表达信息的代码进行注释。

###### 4.3.3 文档注释 ######

文档注释就是指这种注释内容能够生成API帮助文档，称为Kdoc。Kdoc是通过一些工具从Kotlin源代码的文档注释中提取信息，并生成HTML文件，即Kdoc文档。文档注释主要对类（或接口）、属性和函数等进行注释。

**提示**　文档是要给别人看的帮助文档，一般是非私有的属性和函数，以及类或接口等。那些只给自己看的内容可以不用文档注释。

**文档注释标签**

<table> 
 <thead> 
  <tr> 
   <th align="left">标签</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">@author</td> 
   <td align="left">说明类或接口的作者</td> 
  </tr> 
  <tr> 
   <td align="left">@deprecated</td> 
   <td align="left">说明类、接口或成员已经废弃</td> 
  </tr> 
  <tr> 
   <td align="left">@param</td> 
   <td align="left">说明函数参数</td> 
  </tr> 
  <tr> 
   <td align="left">@return</td> 
   <td align="left">说明返回值</td> 
  </tr> 
  <tr> 
   <td align="left">@see</td> 
   <td align="left">参考另一个主题的链接</td> 
  </tr> 
  <tr> 
   <td align="left">@exception</td> 
   <td align="left">说明函数所抛出的异常类</td> 
  </tr> 
  <tr> 
   <td align="left">@throws</td> 
   <td align="left">同@exception标签</td> 
  </tr> 
  <tr> 
   <td align="left">@version</td> 
   <td align="left">类或接口的版本</td> 
  </tr> 
 </tbody> 
</table>

如果想生成Kdoc文档，则需要使用Dokka（https://github.com/Kotlin/dokka）工具，Dokka支持Java和Kotlin混合项目生成Kdoc文档，Dokka提供多种使用方式，可以配置到Gradle、Maven和Ant项目依赖插件中，直接在项目中生成，也可以直接使用命令行工具生成。

[34a7bc8fb0ba4438bd95f757f9ec7375.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/b058a9c6db6b4a35a7f89c639d755520.png