7

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?

Tobia
  • 17,856
  • 6
  • 74
  • 93
  • Also looking for this. Respondents questioning its utility are missing an important use case: KTS self-contained script files, for which the package carries less importance and no other natural place to document the overall script exists. – Chris Hatton Apr 27 '23 at 23:58

2 Answers2

2

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.

yole
  • 92,896
  • 20
  • 260
  • 197
0

If you are using copyright comment so you can put it before the package declaration

If you are using doc comment about information for your file you can put it after the imports

Narek Hayrapetyan
  • 1,731
  • 15
  • 27
  • Do you mean `/** This file ... */` after the imports? Is this an established convention? Will this be picked up by KDoc tools? Wouldn't it be considered (by both machine and humans) as just a comment on the first declaration following it? – Tobia Oct 08 '18 at 02:47