dokka: suppressedFiles / perPackageOption: suppress do not work with Java sources

Having the same issue. Our Android library uses both Java and Kotlin classes. Even the simplest configuration option:

dokkaJavadoc.configure {
  dokkaSourceSets {
    named("main") {

      perPackageOption {
        prefix.set("com.onegini.mobile.sdk.android.internal")
        // also tried
        // prefix = "com.onegini.mobile.sdk.android.internal"
        // matchingRegex.set(".*\.internal.*")
        suppress.set(true)
      }
    }
  }
}

doesn’t work - the internal package is not suppressed.

Tested on

• MacOS Catalina 10.15.6
• Dokka 1.4.20
• Kotlin 1.4.21-2
• com.android.tools.build:gradle:3.6.3

TBH it isn’t a common scenario. Most of the time your public API is what you want to document, apart from the tests, which should have their separate package(s) and then you can just suppress this package. Anyway, suppressing files is not possible (you can probably not document them by manually setting the sourceRoots to the other files, but this is kind of not worth it), you can however suppress a certain class with the @suppress annotation I believe: https://kotlinlang.org/docs/kotlin-doc.html Javadoc comments don’t support any suppressing whatsoever, so there is an Android plugin for Dokka which adds support for the @hide annotation: http://kotlin.github.io/dokka/1.4.32/user_guide/android-plugin/android-plugin/

Thanks for the feedback @robertszuba ! Yeah, I agree that we should have some warnings about that, but I think that those information is not available to us. This is a Gradle configuration and their DSL does not provide any info on which notation was used. I’m also surprised that the old syntax prevented the new one from working correctly, but as I said before, I strongly advise using kts files, because you’d spot those errors way faster (eg. escaping is highlighted, error messages are more meaningful and so on, I believe that even the old syntax does not compile there. Also you can always mix .kts and .gradle files, so migration shouldn’t be that hard)

TBH it isn’t a common scenario. Most of the time your public API is what you want to document, apart from the tests, which should have their separate package(s) and then you can just suppress this package. Anyway, suppressing files is not possible (you can probably not document them by manually setting the sourceRoots to the other files, but this is kind of not worth it), you can however suppress a certain class with the @suppress annotation I believe: https://kotlinlang.org/docs/kotlin-doc.html Javadoc comments don’t support any suppressing whatsoever, so there is an Android plugin for Dokka which adds support for the @hide annotation: http://kotlin.github.io/dokka/1.4.32/user_guide/android-plugin/android-plugin/

Thank you so much for the reply! I understand it might not be common scenario, it’s probably more of an architecture decision, but anyway, the @suppress tag did the magic for me (since my library is purely written in Kotlin), and i’m really happy it worked out.

To sum up and help other in this situation, using the dokka version 1.4.30+, you can do it like this:

To supress a whole package (works for both Java and Kotlin classes): Here i show dokkaHtml but you can use any of the other formats, such as dokkaJavadoc.

dokkaHtml.configure {
    dokkaSourceSets {
        named("main") {
            ...
            perPackageOption {
                matchingRegex.set("com.example.package") // or any other valid regex you wish (only for packages)
                suppress.set(true)
            }
            ...
      }
   }
}

To suppress a file/class: (only for Kotlin docs) Add this to you class documentation.

/**
 * @suppress
 */
class Myclass() {

For javadoc, like @kamildoleglo said, you would need the plugin http://kotlin.github.io/dokka/1.4.32/user_guide/android-plugin/android-plugin/ and use the @hide annotation instead of @suppress.

Hey guys, sorry for bringing this topic up again, but I have been a couple of days trying to suppress packages and files. Only after reading this I was able to suppress a package.

But… What about files/classes?

What if I have only 1 class in the package that I want to suppress documentation and the others not? Has anyone done this successfully?

I’ve tried using matchingRegex.set("com.example.test.MyClass") and it just won’t work. Apparently it only supresses if the regex matches a package.

I’ve searched for a while and couldn’t find any answer for this, I am surprised how no one is talking about it being such a common scenario.