Kotlin函数文档(KDoc)&Dokka使用指南

Dokka是由Kotlin官方维护的生成Kdoc的工具, Kdoc比JavaDoc更加智能和漂亮. 更适合Kotlin. 同时Dokka也支持多种格式输出

这里介绍的是Dokka-1.4.32版本, 0.1.x版本已经被淘汰不推荐使用

我编写的框架全部使用Dokka生成的Kdoc文档, 可作为示例Demo阅读

1. Net 基于协程的网络请求
2. BRV 基于DSL的编写RecyclerView列表
3. Serialize 对象存储
4. Channel 使用协程Channel的事件分发
5. StateLayout 缺省页
6. LogCat 日志输出
7. Tooltip 提醒吐司
8. debugKit 调试窗口
9. StatusBar 透明状态栏
10. RxBus 使用RxJava的事件分发
11. AutoDispose 自动取消RxJava订阅

1. 左侧边栏是包名
2. 左上角可以过滤包名
3. 右上角可以搜索全局文本
4. 右侧悬浮边栏是函数目录

文档

1. 文档
2. GitHub

使用

Dokka支持的输出格式

项目中的build.gradle

dependencies {
	classpath 'org.jetbrains.dokka:dokka-gradle-plugin:1.4.32'
}
复制代码

Module中的build.gradle

apply plugin: 'org.jetbrains.dokka'

// 如果你使用的是新建的Android项目可能是plugins则使用以下添加
/* plugins {
    id 'com.android.library'
    id 'kotlin-android'
    id 'org.jetbrains.dokka' // 改为Id开头
}>/
复制代码

常见配置示例, 这里我配置下Html的输出. 实际上你不配置也可以输出内容, 直接使用

dokkaHtml {
  outputDirectory.set(file("$rootDir/docs/api"))
  suppressInheritedMembers.set(true)
  moduleName.set("Net")
}
复制代码

然后使用AndroidStudio的Gradle任务生成文档

Partial后缀的是应对多Module使用, 具体用法我也不清楚. 可以阅读: 官方说明

详细配置

dokkaHtml {
    outputDirectory.set(buildDir.resolve("dokka"))

    // 设置输出的最终Module名称
    moduleName.set("moduleName")

    // 使用默认值或设置为自定义路径来缓存目录
    // 启用软件包列表缓存
    // 当此设置为默认值时，缓存存储在 $USER_HOME/.cache/dokka
    cacheRoot.set(file("default"))

    // 抑制类似函数toString 或者 equals. 默认 true
    suppressObviousFunctions.set(false)

    // 抑制继承成员, 在当前类中不会描述继承成员
    // 如果你只想抑制toString/equals, 而不抑制data class的compnentN可以使用suppressObviousFunctions
    // 默认 false
    suppressInheritedMembers.set(true)

    // 设置为离线模式, 仅本地访问
    offlineMode.set(false)

    dokkaSourceSets {
        configureEach { //或者可以设置名称, 对于单一平台默认的sourceSet是 `main` and `test`

            // Used when configuring source sets manually for declaring which source sets this one depends on
            dependsOn("otherSourceSetName")

            // Used to remove a source set from documentation, test source sets are suppressed by default  
            suppress.set(false)

            // 是否包含非public的成员
            includeNonPublic.set(false)

            // 不输出废弃成员, 适用于全局, 可以覆写包选项
            skipDeprecated.set(false)

            // 对于未注释文档的警告warring. 适用全局, 可以覆写包选项
            reportUndocumented.set(true)

            // 对于空的package不创建index索引
            skipEmptyPackages.set(true)

            // 将最终显示输出的名称
            displayName.set("JVM")

            // 构建代码分析的平台
            platform.set(org.jetbrains.dokka.Platform.jvm)

            // 将文件手动添加到类路径中
            // This property does not override the classpath collected automatically but appends to it
            classpath.from(file("libs/dependency.jar"))

            // List of files with module and package documentation
            // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
            includes.from("packages.md", "extra.md")

            // 包含示例代码的文件列表 (被 @sample 标签使用的引用)
            samples.from("samples/basic.kt", "samples/advanced.kt")

            // 资源根目录, 默认是 sourceRoots
            sourceRoots.from(file("src"))

            // 指定源代码路径, 如果提供会将声明链接上源代码
            sourceLink {
                // 基于Unix的相对路径 (where you execute gradle respectively). 
                localDirectory.set(file("src/main/kotlin"))

                // 源码网址
                remoteUrl.set(java.net.URL(
                    "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"))
                // 将行号附着到URL后缀. Use #L for GitHub
                remoteLineSuffix.set("#L")
            }

            // 链接到JDK8文档
            jdkVersion.set(8)

            // 禁用在线 kotlin-stdlib 文档
            noStdlibLink.set(false)

            // 禁用在线JDK文档
            noJdkLink.set(false)

            // 禁用在线Android文档 (只在Android项目有效)
            noAndroidSdkLink.set(false)

            // 允许链接到项目依赖库的文档 (由Javadoc或者Dokka生成的依赖文档)
            // 重复链接
            externalDocumentationLink {
                // 生成的文档根目录URL. 必须斜杠结尾
                url.set(URL("https://example.com/docs/"))

                // 如果软件包列表不是位于标准位置
                // packageListUrl = URL("file:///home/user/localdocs/package-list")
            }

            // 指定某个包下定制规则
            perPackageOption {
                matchingRegex.set("kotlin($|\\.).*") // will match kotlin and all sub-packages of it
                // 全部可选, 以下是默认选择:
                skipDeprecated.set(false)
                reportUndocumented.set(true) // Emit warnings about not documented members 
                includeNonPublic.set(false)
            }
            // 抑制指定的package
            perPackageOption {
                matchingRegex.set(""".*\.internal.*""") // will match all .internal packages and sub-packages 
                suppress.set(true)
            }

            // 是否包含文档生成文件, 例如buildDir. 默认不包含
            suppressGeneratedFiles.set(false)
        }
        // Configures a plugin separately from the global configuration
        pluginConfiguration<PluginClass, ConfigurationClass>{
            // values
        }
    }
}
复制代码

自定义样式

Dokka使用3个CSS文件, 修改其内容可以编辑样式

• style.css -负责样式设置页面的主要css文件
• jetbrains-mono.css -在Dokka中使用的字体
• logo-styles.css -徽标样式

需要注意的是重新生成文档会覆盖这些样式文件, 注意备份

块标记

这是在源码中的文档注释使用的标记. 被此标记修饰的会在文档中具备特殊含义

示例

文档语法

Kdoc支持标准的Markdown语法. 这里仅介绍几个常用的

示例代码