Kotlin/Dokka中私有注解在模型中的可见性问题解析

在Kotlin项目文档生成工具Dokka的使用过程中，开发者可能会遇到一个关于注解可见性的特殊问题：当配置documentedVisibilities为PUBLIC和PROTECTED时，预期中私有（private）或内部（internal）可见性的注解类不应该出现在生成的文档模型中。然而实际情况是，虽然这些注解类本身确实没有作为DAnnotation出现在模型中，但它们在被其他公共类使用时，却仍然会以Annotations.Annotation的形式出现在那些公共类的注解列表中。

这个问题的典型表现可以通过以下代码示例来说明：

private annotation class PrivateAnnotation
@PrivateAnnotation
class PublicClass

在这个例子中，PrivateAnnotation本身不会出现在Dokka生成的文档模型中，这是符合预期的。但出乎意料的是，PublicClass的注解列表中却仍然包含PrivateAnnotation的引用。这种行为可能会导致文档使用者困惑，因为他们可能会看到一些本应隐藏的注解信息。

从技术实现角度来看，这个问题涉及到Dokka处理注解可见性的两个不同层面：

1. 对于注解类本身的处理：Dokka正确地遵循了documentedVisibilities的配置，过滤掉了私有和内部可见性的注解类，没有将它们作为DAnnotation包含在模型中。

2. 对于注解使用的处理：Dokka在收集被注解元素的注解信息时，似乎没有应用相同的可见性过滤规则，导致这些私有注解的使用仍然被保留。

这个问题本质上是一个模型一致性问题。理想情况下，Dokka应该在整个文档生成流程中一致地应用可见性过滤规则。也就是说，如果一个注解因为其可见性被排除在模型之外，那么所有使用该注解的地方也应该相应地排除这些注解引用。

对于遇到这个问题的开发者来说，目前可以通过自定义处理来绕过这个问题。但长远来看，这需要在Dokka的核心逻辑中进行修复，确保可见性过滤在整个文档生成过程中得到一致的应用。

理解这个问题对于使用Dokka的Kotlin开发者来说非常重要，特别是在需要严格控制API文档中可见内容的场景下。开发者应该意识到，当前版本的Dokka在注解处理上可能存在这种不一致性，并在审查生成的文档时注意检查这类情况。