Equivalent of package-info.java

Hello,

I am currently porting a code generator from Java to Kotlin, and I currently output some useful information at package level to package-info.java for various packages. I’ve hunted around online, and found a stack overflow from quite a while ago saying that Kotlin doesn’t have anything similar. I also found a question in this forum that was not answered.

I considered just creating a package-info.java corresponding the the Kotlin source, which I guess would be fine as a documentation asset, but it would be ignored by dokka, which kind of goes against the point of the port in the first place.

What I’d like to know is the best approach for documentation at package level?

Chris

2 Likes

Please see the documentation: http://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation

Thanks for the link. I had seen that information, but now I have confirmation that it’s not possible without external configuration. If I’m reading it right, it would appear that there is no convention for code generating package level documentation? So you can wire something up via kdoc parameters but simply interrogating the source tree (or trees) won’t automatically import well structured package level comments?

I know there is probably a good reason for it, but it feels like a regression.

I understand Kotlin is changing all the time. Are there any plans to change this, or possibly have kdoc pick up package-info.java if it is placed in the appropriate position?

4 Likes

At this time we don’t have any plans to add a pure Kotlin way to define package-level annotations and doc comments. Adding support for package-info.java to Dokka is possible; you’re welcome to file a feature request in YouTrack.

1 Like

Done: https://youtrack.jetbrains.com/issue/KT-22384

1 Like

Dokka could, by convention, pick up package-info.md files. They would use the current format but would be found in the same place as package-info.java. As such, migration would be easy: java -> kt, convert JavaDoc comment to flat Markdown, transform trailing package ... to leading # Package ....

2 Likes

I’m kind of a Gradle noob, so I’m probably doing something wrong. I tried to follow the instructions https://kotlinlang.org/docs/reference/kotlin-doc.html?&_ga=2.218563097.1608702429.1598823772-1501025433.1597953643#module-and-package-documentation but the Javadoc output does not seem to be affected by my package.md or module.md files. Here’s how I configured dokka:

tasks.dokkaHtml.configure {
    dokkaSourceSets {
        configureEach { // Or source set name, for single-platform the default source sets are `main` and `test`
            // List of files with module and package documentation
            // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
            includes = listOf("package.md", "module.md")
        }
    }
}

Did I put my .md files in the wrong place? One is in the project root, the other in the main package of the source tree. What am I doing wrong?

My full project is here:
https://github.com/GlenKPeterson/Indented

I’m running with ./gradlew clean assemble dokkaJavadoc

The link does not answer the question any more anchor is gone.

The documentation is here: Module documentation | Kotlin Documentation