如何为ktlint创建自定义规则以检测无效注释块格式

问题说明 #

当前Ktlint默认规则无法识别这类存在多余空行的KDoc注释不良格式：

/**
 * 
 * 
 * */

期望能检测并修复为标准格式：

/**
 *
 */

自定义规则实现方案 #

Ktlint支持通过自定义规则扩展检测逻辑，以下是具体实现步骤：

1. 创建自定义规则类
   基于Ktlint的规则API，编写检测KDoc空行的规则。核心是解析KDoc的AST节点，检查注释内容中的空行数量：

import com.pinterest.ktlint.core.Rule
import com.pinterest.ktlint.core.RuleProvider
import com.pinterest.ktlint.core.ast.ElementType.KDOC
import org.jetbrains.kotlin.com.intellij.lang.ASTNode
import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.LeafPsiElement

class EmptyKDocRule : Rule {
    override fun visitNode(node: ASTNode, autoCorrect: Boolean, emit: (offset: Int, errorMessage: String, canBeAutoCorrected: Boolean) -> Unit) {
        if (node.elementType == KDOC) {
            val kdocText = node.text
            // 匹配有多余空*行的KDoc：/** 后有多个空的 * 行
            val badPattern = Regex("/\\*\\*\n( \\*\\s*\n){2,} \\*\\*/")
            if (badPattern.containsMatchIn(kdocText)) {
                val offset = node.startOffset
                emit(offset, "KDoc存在多余空行，需简化为标准格式", true)
                if (autoCorrect) {
                    // 替换为标准空KDoc格式
                    (node as LeafPsiElement).rawText = "/**\n *\n */"
                }
            }
        }
    }
}

object EmptyKDocRuleProvider : RuleProvider {
    override fun get() = EmptyKDocRule()
}

2. 配置Ktlint加载自定义规则
   在项目的ktlint.yml中添加自定义规则的配置（如果使用Gradle/Maven插件，需确保规则类在类路径中）：

rules:
  - "custom:empty-kdoc"

同时，将自定义规则打包为JAR，放入Ktlint的规则目录，或者在构建脚本中依赖该规则模块。

3. 验证规则效果
   运行Ktlint检测命令：

ktlint --relative

规则会自动识别不良格式的KDoc并提示错误，加上--fix参数可自动修复为标准格式：

ktlint --relative --fix

补充说明 #

• 上述规则针对空KDoc的情况，若需要支持非空KDoc中多余空行的检测，可调整正则表达式和修复逻辑，比如匹配*开头的连续空行。
• 确保使用的Ktlint版本与规则API兼容（不同版本的Rule接口可能有差异，建议参考对应版本的官方文档调整）。

内容的提问来源于stack exchange，提问作者Mohamed Bilal D