疯狂kotlin讲义连载之Kotlin的基础类型--注释

Kotlin的注释与Java注释基本保持一致，Kotlin注释一样支持单行注释、多行注释和文档注释。

 单行注释和多行注释

单行注释就是在程序中注释一行代码，在Kotlin语言中，将双斜线（//）放在须要注释的内容以前，就能够了；多行注释是指一次性地将程序中的多行代码注释掉，在Kotlin语言中，使用“/*”和“*/”将程序中须要注释的内容包含起来，“/*”表示注释开始，而“*/”表示注释结束。

须要指出的是：Java语言的多行注释不支持嵌套，而Kotlin语言的多行注释支持嵌套，这样用起来就更方便了。

下面代码中增长了单行注释和多行注释。

程序清单：codes\02\2.1\comment.kt

/*

这里面的内容所有是多行注释

Kotlin语言真的很简单

*/

fun main(args: Array<String>) {

// 这是一行简单的注释

println("Hello World!")

// print("这行代码被注释了，将不会被编译、执行!")

/* 这是第一个多行注释的开头

/* 这是第二个被嵌套的多行注释 */

这是第一个多行注释的结尾 */

}

注意上面代码中最后一段粗体字注释，这段多行注释中再次嵌套了多行注释，这在Java语言中是不容许的，但Kotlin是容许的。可见：Kotlin的多行注释能够嵌套。也就是说，在/*...*/多行注释块内，能够再次使用/*...*/添加多行注释。当使用多行注释嵌套另外一个多行注释时，只要注意先插入第二个注释块的终止标记，再插入第一个注释块的终止标记便可。

除此以外，添加注释也是调试程序的一个重要方式：若是以为某段代码可能有问题，能够先把这段代码注释起来，让编译器忽略这段代码，再次编译、运行这个程序，若是能够正常编译、运行，则能够说明错误就是由这段代码引发的，这样就缩小了错误所在的范围，有利于排错；若是依然出现相同的错误，则能够说明这个错误不是由这段代码引发的，一样也缩小了错误所在的范围。

 文档注释

Kotlin的文档注释和Java的文档注释相同，一样使用/**和*/来注释文档注释，中间部分所有都是文档注释，会被提取到API文档中。

下面先编写一个KdocTest类，这个类里包含了对类、方法的文档注释。

程序清单：codes\02\2.1\KdocTest.kt

package lee

/**

* Description:

* 网站: <a href="http://www.crazyit.org">疯狂Java联盟</a>

* Copyright (C), 2001-2018, Yeeku.H.Lee

* This program is protected by copyright laws.

* Program Name:

* Date:

* @author Yeeku.H.Lee kongyeeku@163.com

* @version 1.0

* @property name the name of this group.

* @constructor Creates an empty group.

*/

public class KDocTest {

/**

* 一个作加法的简单方法

* @param a 第一个加数

* @param b 第二个加数

* @return 两个数的和

*/

public fun add(a: Int, b: Int): Int {

return a + b

}

}

再编写一个test文件，该文件包含了一个公共函数。

程序清单：codes\02\2.1\test.kt

package yeeku

/**

* 打印消息的简单函数

* @param msg 要显示的消息

*/

fun showMsg(msg: String){

println(msg);

}

上面Kotlin程序中粗体字标识部分就是文档注释。编写好上面的Kotlin程序后，接下来须要使用Dokka工具来生成API文档。

注意：必定要为上面源程序指定包名，不然Dokka工具不会提取KDoc生成API文档。

Kotlin的SDK默认不包含Dokka工具，所以开发者须要自行下载，登陆https://github.com/Kotlin/dokka便可下载该工具，下载完成后获得一个dokka-fatjar.jar文件，该文件是一个可执行的JAR包，执行该JAR包便可启动Dokka工具。

Dokka工具的基础用法以下：

java -jar dokka-fatjar.jar <源文件或目录> <参数>

Dokka工具可对源文件、包生成API文档，在上面的语法格式中，Kotlin源文件能够支持通配符，例如，使用*.kt来表明当前路径下全部的Kotlin源文件。Dokka的经常使用参数有以下几个。

•  -output <directory>：该参数指定生成的API文档的存放路径，该参数的默认值为out，也就是将生成的API文档放在out目录下。
  
•  -format：该参数指定生成的API文档的格式。
  
• format参数指定API文档格式时支持以下经常使用格式选项。
  
•  html：生成最简的HTML格式的API文档。
  
•  javadoc：生成符合javadoc格式的API文档。
  
•  html-as-java：基本上html类似，但会使用Java语法。
  

除此以外，Dokka工具还包含了大量其余选项，读者能够经过https://github.com/Kotlin/dokka来了解它们的更多使用细节。

在命令行窗口执行以下命令来为刚刚编写的两个Kotlin程序生成API文档：

java -jar dokka-fatjar.jar KDocTest.kt test.kt

在KDotTest.kt和test.kt所在路径下执行上面命令，能够看到生成API文档的提示信息。进入KDotTest.kt和test.kt所在路径，能够看到一个out文件夹，该文件夹下的内容就是刚刚生成的API文档，进入out/doc路径下，打开index.html文件，将看到如图2.1所示的页面。

图2.1 生成的API文档

单击图2.1所示API文档上方的lee或yeeku包，便可进入该包的详细页面，便可看到该包所包含的函数和类。

若是开发者但愿生成相似javadoc格式的API文档（通常不建议），能够在使用Dokka工具时添加-format选项，并为该选项指定javadoc选项值。例如输入以下命令。

java -jar dokka-fatjar.jar KDocTest.kt test.kt -format javadoc

再次打开out/doc目录下的index.html页面，便可看到如图2.2所示的API文档。

图2.2 Dokka工具生成javadoc样式的文档

图2.2所示的API文档样式是咱们熟悉的javadoc样式了。通常来讲，并不建议使用Dokka工具来生成javadoc样式的API文档，由于等咱们真正习惯了Dokka默认的文档样式以后，也会以为Dokka默认的文档样式也很方便易用。

以上内容节选自《疯狂Kotlin讲义》：一本让您最直接认识Kotlin的疯狂讲义

本书即将于2017年11月发售 敬请期待

往期连载

第一期： 第一期：juejin.im/post/59c0b7…

第二期：juejin.im/post/59c1d6…

第三期：juejin.im/post/59e407…

第四期：juejin.im/post/59ed77…

相关书籍《疯狂Android讲义》https://item.jd.com/11689014.html