Kotlin-为Android项目生成Doc文档

类似于Java中的JavaDoc工具，Kotlin的官方也发布了一款生成Kotlin文档工具。dokka
不过它确实不是很好用。

1.引入依赖

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.9.17"
    }
}
repositories {
    jcenter() // or maven { url 'https://dl.bintray.com/kotlin/dokka' }
}

坑1：截止在我写这边文档时候，该工具的最新版本为0.10.0。在这个版本中，作者将两个插件进行了合并（一个适用于Android项目的插件，一个则用于通用Kotlin项目插件）。导致了出现了一个大坑。详情请见这里 [https://github.com/Kotlin/dokka/issues/213(https://github.com/Kotlin/dokka/issues/213)。

经过一早上的踩坑折腾，发现在回退到上一个版本，0.9.17版本没出现类似问题。

2. 配置使用

apply plugin: 'kotlin-android-extensions'
apply plugin: 'kotlin-kapt'
// 添加插件
apply plugin: 'org.jetbrains.dokka-android'
...
android {
    ...
// 声明dokka配置DSL
    dokka {
    // 输出格式，目前支持五种，html, javadoc,html-as-java, markdown,kotlin-website*
        outputFormat = 'html'
      // 文档输出目录
        outputDirectory = "$buildDir/javadoc"
    }
}

然后同步项目之后，该插件会为项目添加一个dokka的task。

image.png

坑2：点击执行此任务之后。首先插件会构建你项目中的所有的构建变体（flavor）。没错，如果你的项目中有dev，release变体，那么这两个变体都会构建一遍，出现任何构建不通过都会导致生成文档失败。比如说。在某些构建变体中没有配置BuildConfig属性，ManifestPalceHolder还未来得及配置，都会导致构建不通过。
WTF，你就不能像JavaDoc那样安安静静像生成个文档。。

坑3：GC overhead limit exceeded。解决了上一个问题，又出现了一个oom的问题。这个问题也算是常见，不过我这个总共不超过十个class文件，居然翻车了。。好吧，果断在根目录下gradle.properties文件中配置扩大一下堆栈大小

org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError

在成功构建完所有的构建变体任务后，终于看到了在输出目录outputDirectory中的出现了javadoc文件夹。

image.png

打开index页面，你就可以看到dokka为项目生成的文档了。

image.png

image.png

坑4：可以看到，dakko确实帮我们生成了类文档，但是居然androidx开头的是什么鬼？？打开一开里面全都是一些R文件的声明。
很明显，dokka有点水土不服，因为在android构建过程中确实会生成很多R文件。

image.png

那我只想生成项目src目录下的代码文档，其他的我统统不想要。怎么办？
翻遍了dakko文档，解决方案不是没有，只是在我看来不是很完美。在dakko中是通过 packageOptions 这个DSL配置来声明相关配置的。比如：

dokka {
        outputFormat = 'html'
        outputDirectory = "$buildDir/javadoc"
        packageOptions {
          // 所操作的包的前缀，包括androidx一下所有的子包。通配符无效
            prefix = "androidx"
         // 该包全部不生成文档
            suppress = true
        }
    }

在以上声明中，dokka就不会为androidx作为包名前缀的类生成文档。问题似乎得到了解决。但是这是一种舍近求远的方法。就好比你去一家店想买一杯奶茶，老板居然问你不想喝什么口味的。。因为在后续的开发中你可能还会引入新的包，dokka可能会为其他R文件生成以其他报名开头的文档。那么此时你必须继续添加packageOptions配置。。