在哪里放置 Kotlin 文件的文档（不是包，不是模块，不是 class）

Question

我应该在哪里发表关于 Kotlin 源文件的评论？

类和其他对象有 KDoc:

/**
 * Summary
 *
 * Rest of documentation goes here.
 */
class A {
    ...
}

但是我应该把这样的东西放在哪里呢？

// This file contains constants shared between frontend and backend.
// Make sure not to use any JVM- or JS-specific import.
// ...

在package声明之前？在它之后？我应该使用 KDoc 注释/块注释/行注释吗？

有什么约定俗成的吗？

Answer 1

如果您使用版权注释，那么您可以将其放在 package 声明之前

如果您使用有关文件信息的文档注释，您可以将其放在 imports

之后

Answer 2

文件不是 API 的一部分，因此没有地方可以放置文件的文档以便 Dokka 可以选择它。您应该对此类文档使用常规（而不是 KDoc）注释，并将其放在人类读者容易找到的地方（很可能在导入块之后），因为机器对这些信息没有用处。

Where to put documentation for a Kotlin file (not package, not module, not class)