Где разместить документацию для файла Kotlin (не пакет, не модуль, не класс)
Где я должен оставить комментарий о исходном файле 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 / блокировать комментарии / комментарии к строкам?
Есть ли какая-либо установленная конвенция?
2 ответа
Файл не является частью API, поэтому нет места, где вы можете поместить документацию для файла, чтобы он был выбран Dokka. Вы должны использовать регулярные (не KDoc) комментарии для такой документации и поместить ее в место, где ее будет удобно найти для читателей-людей (скорее всего после блока импорта), потому что машины не используют эту информацию.
Если вы используете комментарий об авторских правах, вы можете поместить его до package декларация
Если вы используете документальный комментарий об информации для вашего файла, вы можете поместить его после imports