Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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?

like image 814
Tobia Avatar asked Oct 07 '18 06:10

Tobia


1 Answers

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.

like image 110
yole Avatar answered Dec 22 '22 15:12

yole