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默认的文档样式也很方便易用。
6万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
