瘋狂kotlin講義連載之Kotlin的基礎類型--註釋

時間 2019-11-24

標籤瘋狂 kotlin 講義連載基礎類型註釋简体版

原文原文鏈接

Kotlin的註釋與Java註釋基本保持一致，Kotlin註釋一樣支持單行註釋、多行註釋和文檔註釋。

單行註釋和多行註釋

單行註釋就是在程序中註釋一行代碼，在Kotlin語言中，將雙斜線（//）放在須要註釋的內容以前，就能夠了；多行註釋是指一次性地將程序中的多行代碼註釋掉，在Kotlin語言中，使用「/*」和「*/」將程序中須要註釋的內容包含起來，「/*」表示註釋開始，而「*/」表示註釋結束。html

須要指出的是：Java語言的多行註釋不支持嵌套，而Kotlin語言的多行註釋支持嵌套，這樣用起來就更方便了。java

下面代碼中增長了單行註釋和多行註釋。git

程序清單：codes\02\2.1\comment.ktgithub

/*編程

這裏面的內容所有是多行註釋app

Kotlin語言真的很簡單ide

*/函數

fun main(args: Array<String>) {工具

// 這是一行簡單的註釋post

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所示的頁面。