CODEWITHSUNDEEP
inheritancedocumentationkotlingradle-pluginkotlin-dokka
0xbe5077ed
0xbe5077ed

Reputation: 4765

Suppress Dokka complaints about "No documentation for com.foo.Bar$toString()"?

I'm using the Gradle Dokka plugin version 0.9.16-eap-1 to generate documentation for some Kotlin code.

I'm a no broken windows kind of person and consequently a bit frustrated that the plugin generates a tonne of messages for classes for which I haven't explicitly documented an overridden method which is adequately documented in the base class, eg:

package com.foo
/**
 * A silly class to demonstrate silliness.
 */
class Bar : java.io.InputStream() {
    override fun read() = -1
    override fun toString() = "BAZ!"
}

For this class Dokka reprimands:

No documentation for com.foo.Bar$read() (Bar.kt:6)
No documentation for com.foo.Bar$toString() (Bar.kt:7)

This is slightly tedious, as I don't want to have to redundantly redundantly document everything with copy-paste documentation.

Looking at the Dokka README.md, the only relevant configuration options I see are:

dokka {
    ...
    // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
    reportNotDocumented = true 
    ...
    // Allows to customize documentation generation options on a per-package basis
    // Repeat for multiple packageOptions
    packageOptions {
        ...
        reportUndocumented = true // Emit warnings about not documented members 
        ...
    }
}

But I don't want to suppress warnings about undocumented stuff. That would be just as bad. All I want to do is suppress warnings about undocumented override funs on the assumption I'm deliberately not repeating myself not repeating myself.

Does anyone know if there's an option to switch off the warnings just for override fun?

Upvotes: 4

Views: 1484

Answers (2)

Tulsiram Rathod
Tulsiram Rathod

Reputation: 1946

Probably You need to add below: 

// No default documentation link to kotlin-stdlib
  noStdlibLink = false

final could is like:

dokka {
        // refer https://github.com/Kotlin/dokka#output-formats
        outputFormat = 'html'
        outputDirectory = "$buildDir/javadoc"
        // Do not create index pages for empty packages
        skipEmptyPackages = true
        // No default documentation link to kotlin-stdlib
        noStdlibLink = false
    }

As noStdlibLink = false will be generate document for inherited function by providing link to kotlin-stdlib. you can refer more here.

I have used dokka version 0.9.17.

Output will be:

Task :app:dokka UP-TO-DATE

BUILD SUCCESSFUL in 1m 13s
104 actionable tasks: 35 executed, 69 up-to-date
5:53:38 PM: Task execution finished 'dokka'.

Upvotes: 0

Archibald
Archibald

Reputation: 1403

For your specific case use @suppress

class MyAndroidActivity: Activity {

    /** @suppress */
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
    }

}

This way you will exclude the overridden function from the documentation completely.

However, if you want to retain a reference to the API call in the documentation simply add an empty one-line docstring close to the element (it will disable the warning):

class MyAndroidActivity: Activity {

    /***/
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
    }

}

Upvotes: 3

Related Questions