Android Studio中Kotlin函数文档模板自动生成配置咨询

阿华AIGC实验室

2026-5-19

解决Kotlin在Android Studio中自动生成带参数/返回值的文档注释问题

嘿，我之前也碰到过这个问题！其实不用急着折腾Dokka，先看看Android Studio内置的设置就能解决大部分需求，下面给你几个靠谱的方案：

方案一：调整IDE内置的Kotlin注释设置

这是最省心的方法，Android Studio本身就支持给Kotlin函数生成带参数和返回值的注释模板，只是默认可能没开启：

打开Settings（快捷键Ctrl+Alt+S，或者顶部菜单栏File→Settings）
依次导航到 Editor → Code Style → Kotlin → Documentation Comments
在右侧面板里，勾选这些选项：
- Add @param tags for method parameters
- Add @return tag for non-void methods
- 还可以根据需求勾选Add @throws tags for exceptions from method signature
点击Apply和OK保存设置

现在回到代码里，在函数上方输入/**然后回车，就能自动生成包含所有参数、返回值的注释模板啦！

方案二：自定义Live Templates（更灵活的模板）

如果内置模板不符合你的格式需求，还可以自己定义Live Templates来生成注释：

打开Settings→Editor→Live Templates
点击右侧的+号，先选择Template Group，新建一个组（比如叫KotlinCustomDocs）
选中刚新建的组，再点击+号选择Live Template：
- Abbreviation：填/**（和内置的触发词一致，方便记忆）
- Template text：粘贴下面的内容：
```
/**
 * $DESCRIPTION$
 $PARAMS$
 * @return $RETURN$
 */
```
- 点击Edit variables按钮，给变量设置对应的表达式：
  - DESCRIPTION：留空，让你手动输入函数描述
  - PARAMS：选择groovyScript，粘贴这段脚本：
```
groovyScript("def result=''; def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {result+=' * @param ' + params[i] + ((i < params.size() - 1) ? '\\n' : '')}; return result", methodParameters())
```
  - RETURN：选择groovyScript，粘贴这段脚本：
```
groovyScript("return \"${_1}\" == 'void' ? '' : '* @return ' + \"${_1}\"", methodReturnType())
```
- 在底部的Applicable in Kotlin里，勾选所有适用的范围（比如Declaration）
保存设置后，在函数上方输入/**按Tab键，就能生成你自定义的注释模板了

方案三：搞清楚Dokka的作用（别混淆啦）

注意：Dokka主要是用来生成项目静态文档的，和IDE里的自动注释模板不是一回事，很多人会把这俩搞混。如果你确实需要用Dokka生成文档，给你个靠谱的配置方式：
在Module级的build.gradle.kts（或build.gradle）里做以下配置：

在plugins块里添加Dokka插件：

plugins {
    id("com.android.application") // 或com.android.library
    id("org.jetbrains.kotlin.android")
    id("org.jetbrains.dokka") version "1.8.20" // 版本和你的Kotlin版本匹配
}

添加Dokka的配置块：

tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
    dokkaSourceSets {
        named("main") {
            jdkVersion.set(11) // 对应你的项目JDK版本
            // 可选：配置源码链接，方便文档跳转
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(uri("https://github.com/你的用户名/你的项目名/blob/main/src/main/kotlin/").toURL())
                remoteLineSuffix.set("#L")
            }
        }
    }
}