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

Question

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?

Hmm. Apparently the function [should have documentation](https://stackoverflow.com/a/35838071/7366707). — Salem, Dec 09 '17 at 07:17
I don't understand your comment... What do you mean "should" and why is that apparent from the link? — 0xbe5077ed, Dec 09 '17 at 09:59
From the post: "Dokka always copies the documentation from a base member to an inherited one if the inherited member does not have its own documentation." Implying that the overridden member is documented. Also from the post: there is nothing similar to `@inheritdoc` in Java. — Salem, Dec 09 '17 at 10:14
Hmmm, indeed. But I'm not asking about what Dokka does in terms of inserting inherited documentation. I'm asking how to make it stop polluting my build logs with pointless warning messages. — 0xbe5077ed, Dec 09 '17 at 10:35

Archibald · Answer 1 · 2018-12-02T10:28:26.090

3

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?) {
        ...
    }

}

edited Dec 02 '18 at 10:28

answered Jan 14 '18 at 18:30

Archibald

1,305
1
14
19

2

This doesn't really solve the problem though. The real problem is in that Dokka is unable to inherit the Kotlin stdlib docs. An alternative way to look at this is to suppress overridden properties and funs automatically. – SOFe Dec 02 '18 at 10:09

Tulsiram Rathod · Answer 2 · 2019-01-21T12:25:06.413

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'.

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

2 Answers2