Kotlin/Dokka 插件开发教程：实现隐藏内部API的文档生成插件-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00254/article/details/148575536

Kotlin/Dokka 插件开发教程：实现隐藏内部API的文档生成插件

dokka API documentation engine for Kotlin 项目地址: https://gitcode.com/gh_mirrors/do/dokka

前言

在Kotlin项目开发中，良好的API文档对于团队协作和代码维护至关重要。Dokka作为Kotlin的官方文档生成工具，提供了强大的插件机制允许开发者扩展其功能。本文将手把手教你开发一个实用的Dokka插件，用于自动隐藏标记为内部的API文档。

插件功能概述

我们将开发一个名为HideInternalApiPlugin的Dokka插件，它能自动识别并过滤掉被@Internal注解标记的类、函数等元素，使其不出现在最终生成的文档中。这种功能在企业级开发中非常实用，可以保护内部实现细节不被公开暴露。

开发环境准备

使用Dokka插件模板创建项目
重命名默认包名为org.example.dokka.plugin
修改主插件类名为HideInternalApiPlugin
更新META-INF/services中的服务注册文件
在build.gradle.kts中配置正确的groupId和版本号

核心实现原理

Dokka的文档生成过程分为多个阶段，我们需要在预处理阶段(PreMergeDocumentableTransformer)介入，过滤掉不应出现在文档中的元素。

继承抽象过滤器

Dokka已经提供了一个方便的抽象类SuppressedByConditionDocumentableFilterTransformer，我们只需实现其shouldBeSuppressed方法：

class HideInternalApiTransformer(context: DokkaContext) : 
    SuppressedByConditionDocumentableFilterTransformer(context) {
    
    override fun shouldBeSuppressed(d: Documentable): Boolean {
        // 实现过滤逻辑
    }
}

注解检测实现

通过分析Documentable对象的extra属性，我们可以获取到元素上的所有注解：

val annotations: List<Annotations.Annotation> =
    (d as? WithExtraProperties<*>)
        ?.extra
        ?.allOfType<Annotations>()
        ?.flatMap { it.directAnnotations.values.flatten() }
        ?: emptyList()

然后检查是否存在目标注解：

private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean {
    return annotation.dri.packageName == "org.jetbrains.dokka.internal.test" 
            && annotation.dri.classNames == "Internal"
}

插件注册

在插件主类中注册我们的转换器：

class HideInternalApiPlugin : DokkaPlugin() {
    val myFilterExtension by extending {
        plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer
    }
}

调试技巧

使用publishToMavenLocal发布插件到本地仓库
在测试项目中引用本地插件版本
通过-Dorg.gradle.debug=true启用调试
在IDE中附加远程调试器
观察Documentable对象的结构和属性

单元测试实践

Dokka提供了完善的测试基础设施，我们可以编写自动化测试验证插件行为：

class HideInternalApiPluginTest : BaseAbstractTest() {
    @Test
    fun `should hide annotated functions`() {
        testInline(
            """
            |package org.jetbrains.dokka.internal.test
            |
            |annotation class Internal
            |
            |fun shouldBeVisible() {}
            |
            |@Internal
            |fun shouldBeExcludedFromDocumentation() {}
            """.trimMargin(),
            pluginOverrides = listOf(HideInternalApiPlugin())
        ) {
            preMergeDocumentablesTransformationStage = { modules ->
                // 验证结果
                assertEquals(1, packageFunctions.size)
                assertEquals("shouldBeVisible", packageFunctions[0].name)
            }
        }
    }
}