Kotlin
Provide a way to supply source files of external dependencies for inheriting documentation
If extending a class or interface from outside my own module, the documentation of overridden functions is not inherited.
Example:
class MyList : List<String> {
override fun contains(element: String): Boolean { /* ... */ }
// ...
}
Calling dokka produces an empty function doc and the warning:
No documentation for my.package.MyList$contains(kotlin.String)
Seems to be still relevant in 1.7.20, but with a different message.
Configuration:
tasks.withType<DokkaTask>().configureEach {
dokkaSourceSets.configureEach {
reportUndocumented.set(true)
}
}
Reproducer:
class MyList(override val size: Int) : List<String> {
override fun contains(element: String): Boolean = TODO("Not yet implemented")
override fun containsAll(elements: Collection<String>): Boolean = TODO("Not yet implemented")
override fun get(index: Int): String = TODO("Not yet implemented")
override fun isEmpty(): Boolean = TODO("Not yet implemented")
override fun iterator(): Iterator<String> = TODO("Not yet implemented")
override fun listIterator(): ListIterator<String> = TODO("Not yet implemented")
override fun listIterator(index: Int): ListIterator<String> = TODO("Not yet implemented")
override fun subList(fromIndex: Int, toIndex: Int): List<String> = TODO("Not yet implemented")
override fun lastIndexOf(element: String): Int = TODO("Not yet implemented")
override fun indexOf(element: String): Int = TODO("Not yet implemented")
}
Warning messages:
Undocumented: me.beresnev.dokka.debug/MyList/contains/#kotlin.String/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/containsAll/#kotlin.collections.Collection[kotlin.String]/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/get/#kotlin.Int/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/isEmpty/#/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/iterator/#/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/listIterator/#/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/listIterator/#kotlin.Int/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/subList/#kotlin.Int#kotlin.Int/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/lastIndexOf/#kotlin.String/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/indexOf/#kotlin.String/ (jvm)
Undocumented: me.beresnev.dokka.debug/MyList/size/#/ (jvm
No documentation is inherited because Dokka does not have access to the source files of Kotlin stdlib, where List is declared and documented, so it doesn't see any documentation it can inherit.
It is possible to download stdlib sources, configure them as Dokka source roots and suppress them - this way, Dokka should be able to extract documentation from the sources, but will not build documentation for it.
However, it's not convinient to say the least, so we've decided to modify this issue to be a feature request.
Users should be able to feed Dokka source files of other libraries which it will use for inheriting documentation and providing additional context. How and which formats it should accept is to be researched and discussed.
Integration with other tools should be considered - for example, it's possible to download dependency sources by running mvn dependency:sources, or by using the idea Gradle plugin:
idea {
module {
downloadSources = true
}
}
Is there any update an this request? I'm having a multi module project, where documentation from one module is not inherited by another module.
Is there maybe a workaround?
where documentation from one module is not inherited by another module.
It looks like a module dependency is viewed as any other external dependency, even though we should be able to access the sources of the other module or at least simplify configuration in such cases.
Is there maybe a workaround?
I threw together a function that can add source files of another project within the same build, so that Dokka can find parent declarations and inherit documentation. Tested it on our multi-module example
Should be put into a build file:
// Usage example
dokkaAddSourceFilesFrom(project(":parentProject:childProjectA"))
/**
* Allows you to add source files of a project to be used for
* inheriting documentation.
*
* Dokka automatically inherits documentation if it has the source
* files of the parent declaration. However, Dokka usually does not have access to
* the source files of external dependencies/libraries.
*
* If you are using Dokka in a multi-project build, other projects are viewed
* as external dependencies, so Dokka does not have access to its source files
* by default. However, because all projects are part of the same build, it's possible
* to feed Dokka the sources of another [project], using this method.
*/
fun dokkaAddSourceFilesFrom(project: Project) {
val sourceDirectories = project
.sourceSets
.map { it.allSource.sourceDirectories }
.flatten()
tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaLeafTask>().configureEach {
dokkaSourceSets.configureEach {
// Add sources to be analyzed by Dokka,
// it will use it for inheriting documentation
sourceRoots.from(sourceDirectories)
// Suppress these sources from
// being generated in Documentation
suppressedFiles.from(sourceDirectories)
}
}
}
It's for Gradle and Kotlin DSL only, but you can re-write it to Groovy DSL, and the Maven runner should have similar options.
Same idea could be used to add any other sources for inheritance - for instance, if you have a zip archive of a library or something similar - simply pass the paths of src directories to both sourceRoots and supressedFiles.
@IgnatBeresnev the suggestion above would only work for local modules, right?
Would be nice to be able to include dokka data in publications (maybe a separate Gradle variant?) so that it would work accross Gradle builds (might even simplify the multi-module configuration?)
would only work for local modules, right?
yeah, the provided workaround will work for local modules only.
For external modules, similar workaround is possible, but you will need to manually setup downloading of sources from Maven Central (via separate Gradle configuration with attributes selector) - luckily, most of the time they are available.
And so you will be able to provide them in the same way to sourceRoots + suppressedFiles. It's not an easy task, but doable. Also, it could significantly improve Dokka execution time, as much more sources should be analysed.
Would be nice to be able to include dokka data in publications
Yeah, the idea is nice, and we have already several feature requests like this, specifically https://github.com/Kotlin/dokka/issues/2787 and https://github.com/Kotlin/dokka/issues/621. But there is one problem - it's not that easy :) If we are willing to publish something (not only to be used internally for multi-module cases), it should be properly designed:
- with backward/forward compatibility in mind
- should be evolvable with support for new language features
- KDoc itself should be correctly specified (there are some questions now, specifically in scope of KMP)
- what should be included and what not
- what it should be? HTML(like javadoc)/JSON/ZIP(like swift docc)/etc?
- and so on...
We have some internal discussions on this topic, but there is no yet final decision.
Nice! For the record, I'd be pretty happy already with an initial version that has no backward compatibility guarantees and no specified format at all.
Those things can be added later on. I understand this is more or less what happened with the K/N .klib format.
Having something usable without those guarantees would already be a huge step and allow me to have much better KDoc for the libs I have control over.
what it should be? HTML(like javadoc)/JSON/ZIP(like swift docc)/etc?
Would definitely love to see some rendering-neutral intermediate representation. JSON would probably work. Not sure about swift docc but HTML sure doesn't sound too great. If I depend on a lib that only publishes HTML but I want markdown => I'm stuck.