《Kotlin实战》-附录

news2024/11/9 6:22:29

附录

本部分内容只是简单列举下Kotlin应用以便指引进一步深入学习Kotlin。

附录A：构建Kotlin项目

本节只会记录下gradle的应用，其他需要时请自行搜索查看。

A.1 用Gradle构建Kotlin代码的项目

构建Kotlin项目的标准Gradle脚本如下：

buildscipt{
    ext.kotlin_version = "1.0.6"
    repositories{
        mavenCentral()
    }
    dependencies{
        classpath "org.jetbrains.kotlin:" + "kotlin-gradle-plugin:$kotlin_version"
    }
}

apply plugin:'java'
apply plugin:'kotlin'
repositories{
     mavenCentral()
}
 
dependencies{
     classpath "org.jetbrains.kotlin:" + "kotlin-gradle-plugin:$kotlin_version"
}

脚本在以下位置查找Kotlin源文件：

代码源文件位置：src/main/java和src/main/kotlin
测试源文件位置：src/test/java和src/test/kotlin

如果使用Kotlin反射，需要添加反射库：
compile "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"

A.1.1 用Gradle来构建Kotlin Android应用

Android应用和普通Java应用构建过程不同，需要添加
apply plugin:'kotlin-android'
而不是
apply plugin:'kotlin'

如果需要把Kotlin源代码放在特定目录下，如src/main/kotlin，则需要注册他们

android{
    ...
    sourceSets{
        main.java.srcDirs += 'src/main/kotlin'
    }
}

A.1.2 构建需要处理注解的项目

如果要在Kotlin使用时依赖注解处理，需要添加：
apply plugin: 'kotlin-kapt'

如果试图引入Kotlin到现有的一个使用注解处理的Java项目中，那么需要删除apt工具的现有配置。
Kotlin注解处理工具包含了Java和Kotlin类的处理，两个单独的注解处理工具是多余的。
可以使用kapt依赖配置来配置注解处理所需的依赖关系。
如下：

dependencies{
    compile 'com.google.dagger:dagger:2.4'
    kapt 'com.google.dagger:dagger-compiler:2.4'
}

如果对androidTest或test使用注解处理器，则对应的kapt配置应该分别为kaptAndroidTest和kaptTest。

A.2 使用Maven来构建Kotlin项目

略

A.3 用Ant来构建Kotlin项目

略

附录B：Kotlin代码的文档化

B.1 给Kotlin代码写文档注释

1.KDoc
为Kotlin声明编写文档注释的格式与Java类似，称为KDoc。
和JavaDoc一样，注释同样以/**开始，并使用@开头的标签来记录声明的特定部分。
两者的主要区别在于，KDoc用来写入注释的格式是Markdown而不是HTML。
KDoc还支持一些额外的约定来引入文档元素，例如函数的形参。
示例：

/**
* Calculates the sum of two numbers,[a] and [b]
*/
fun sum(a:Int,b:Int) = a + b

如上所示，把名称放入括号内，就是在注释中引入一个声明。
这种用法不仅用来记录函数参数，也可以用来引用其他声明。

2.注释中的标签
KDoc使用标签的语法与JavaDoc完全相同。
除了标准的JavaDoc标签以外，还支持额外的特有标签，例如：

@receiver：记录扩展函数或属性的接受者
@sample：用于将指定函数的文本包含在文档文本之中，作为使用正在记录的API的示例

KDoc不支持的一些JavaDoc标签：

@deprecated被替换为@Deprecated
@inheritdoc,Kotlin中文档注释始终通过覆盖声明自动继承。
@code、@literal和@link将替换为相应的Markdown格式

注意，Kotlin团队首选的文档样式是B.1所示的直接文档注释。
只有当参数或返回值具有复杂的语义并且需要从主要文档文本中分离时，才会使用标签。

B.2 生成API文档

Dokka是Kotlin的文档生成工具。其有以下特点：

完全支持跨语言的Java/Kotlin项目，可以读取JavaDoc注释和KDoc注释，并生成覆盖模块的API文档。
支持多种输入格式，包括纯HTML，JavaDoc风格的HTML和Markdown。

可以从命令行运行Dokka，或者把他作为构建脚本的一部分。
以Gradle构建脚本为例：

buildscript{
    ext.dokka_version = '0.9.13'
    repositories{
        jcenter()
    }
    dependencies{
        classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}"
    }
}

apply plugin 'org.jetbrains.dokka'

然后通过./gradlew dokka来为模块生成HTML格式的文档。
其他生成选项可以去查看Dokka文档。