Hi I’m having a lot of trouble with Dokka. My main...

# dokka

[Carson Holzheimer]

Hi I’m having a lot of trouble with Dokka. My main aim is to provide IDE documentation to library consumers for our closed source library. My strategy so far is to create a javadoc jar for only the public api. All of the public api code is java. My publishing.gradle file is in the thread. This works, but the generated javadocs has a lot of missing documentation: @deprecated text is missing, all property docs are missing.
Also, documentation for any files that are in different android build type folders are NOT suppressed.

It’s unrelated to Dokka, but another strategy I tried to enable IDE documentation was to publish the sources jar, just for the public api classes. This works if minification is turned off, but fails if it is turned on, with no documentation showing at all in Android studio. I don’t know how to debug this. Do I need to ensure that absolutely everything in the classes I have sources for is not minified? Is there any way to see error logs for this?

[Carson Holzheimer]

publishing.gradle

tasks {
    dokkaJavadoc {
        suppressObviousFunctions.set(true)
        suppressInheritedMembers.set(true)
        offlineMode.set(true)
        dokkaSourceSets {
            configureEach {
                if (it.name in ["standardStage"]) {
                    suppress.set(false)
                    displayName.set(it.name)
                    def listWithJavaDirPrepended = listOfPublicApiFiles.collect { "src/main/java$it" }
                    sourceRoots.setFrom(files(listWithJavaDirPrepended))
                } else {
                    suppress.set(true)
                }
            }
        }
    }
}

task androidDokkaJar(type: Jar, dependsOn: dokkaJavadoc) {
    archiveClassifier.set('javadoc')
    from "$buildDir/dokka" // The default location for files generated by dokka
}

publishing {
    publications {
        version = rootProject.ext.versionName
        standardStage(MavenPublication) {
            afterEvaluate {
                from components.standardStage
                //artifact androidSourcesJar
                artifact androidDokkaJar
            }
            groupId = 'com.adherium'
            artifactId = "smartchat-stage"
        }
    }
}

[Carson Holzheimer]

Have tried Android Studio Dolphin, Electric Eel, Flamingo, kotlin 1.5.21, 1.7.20, AGP 7.2.2 and 7.3.1. All the same outcome

[Carson Holzheimer]

SO link to sources issue here: https://stackoverflow.com/questions/74637696/published-sources-in-maven-local-repository-not-visible-in-android-studio-ide-if

[Ignat Beresnev]

Hi! I've posted a longer explanation in the issue.

TLDR: Dokka's Javadoc format is just a lookalike (not 100% the same) and it's still in Alpha, so there are noticeable bugs and integration issues with tools that expect the true Javadoc HTML pages. It has lower priority now compared to Dokka's own HTML format, so these issues won't be fixed overnight 😞

If you have the time to fix specific bugs that you find, I'd be happy to assist with the technical aspects of contributing to Dokka and with code reviews

[Ignat Beresnev]

Also, I don't know which version of Dokka you are using, but using the latest might help with some things. We do fix bugs in the Javadoc format, but not as actively as we do for the HTML format.

[Carson Holzheimer]

Thanks. I tried the latest Dev build but it was the same. Your explanation helps me to know I should be pursuing publishing source files for the public api instead, which should mean less room for errors. Any idea why sources don't show in IDE when proguard is enabled?

[Ignat Beresnev]

Any idea why sources don't show in IDE when proguard is enabled?

Unfortunately, no idea as I have virtually no experience with it 😞

[Carson Holzheimer]

For anyone interested, I found that sources for Kotlin files are visible in the IDE, but not java, when minify is enabled. Possibly an intellij java bug?
https://stackoverflow.com/a/74990855/4672107