Search code examples
kotlincommentskdoc

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

Where should I put a comment about a Kotlin source file?

Classes and other objects have KDoc:

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

But where should I put something like this? 

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

Before the package declaration? After it? Should I use KDoc comments / block comments / line comments?

Is there any established convention?

Solution

  • A file is not part of an API, therefore there is no place where you can put documentation for a file so that it will be picked by Dokka. You should use regular (not KDoc) comments for such documentation, and put it into a place where it will be good to find for human readers (most likely after the imports block), because the machines have no use for this information.