Подавить жалобы Dokka на отсутствие документации для com.foo.Bar$toString()?

Я использую плагин Gradle Dokka версии 0.9.16-eap-1 для создания документации для некоторого кода Kotlin.

Я не сторонник сломанных окон и, следовательно, немного разочарован тем, что плагин генерирует массу сообщений для классов, для которых я явно не задокументировал переопределенный метод, который адекватно задокументирован в базовом классе, например< /эм>:

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

За это занятие Докка делает выговор:

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

Это немного утомительно, так как я не хочу избыточно документировать все с помощью копирования и вставки документации.

Глядя на Dokka README.md, единственные подходящие параметры конфигурации, которые я см.:

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

Но я не хочу подавлять предупреждения о недокументированных вещах. Это было бы так же плохо. Все, что я хочу сделать, это подавить предупреждения о недокументированных override развлечениях, предполагая, что я намеренно не повторяюсь, не повторяюсь.

Кто-нибудь знает, есть ли возможность отключить предупреждения только для override fun?


kotlin inheritance documentation gradle-plugin kotlin-dokka
person 0xbe5077ed    schedule 09.12.2017    source источник
comment
Хм. Очевидно, функция должна иметь документацию.   -  person Moira    schedule 09.12.2017
comment
Я не понимаю ваш комментарий ... Что вы имеете в виду, и почему это видно из ссылки?   -  person 0xbe5077ed    schedule 09.12.2017
comment
Из поста: Dokka всегда копирует документацию с базового члена на унаследованный, если у унаследованного члена нет собственной документации. Подразумевается, что переопределенный член задокументирован. Также из поста: ничего похожего на @inheritdoc в Java нет.   -  person Moira    schedule 09.12.2017
comment
Хм, действительно. Но я не спрашиваю о том, что Dokka делает с точки зрения вставки унаследованной документации. Я спрашиваю, как заставить его перестать загрязнять мои журналы сборки бессмысленными предупреждающими сообщениями.   -  person 0xbe5077ed    schedule 09.12.2017

Ответы (2)


arrow_upward
2
arrow_downward

В вашем конкретном случае используйте @suppress

class MyAndroidActivity: Activity {

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

}

Таким образом, вы полностью исключите переопределенную функцию из документации.

Однако, если вы хотите сохранить ссылку на вызов API в документации, просто добавьте пустую однострочную строку документации рядом с элементом (это отключит предупреждение):

class MyAndroidActivity: Activity {

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

}
person Archibald    schedule 14.01.2018
comment
Хотя на самом деле это не решает проблему. Настоящая проблема заключается в том, что Dokka не может наследовать документы Kotlin stdlib. Альтернативный способ взглянуть на это — автоматически подавить переопределенные свойства и развлечения. - person SOFe; 02.12.2018

arrow_upward
0
arrow_downward

Вероятно, вам нужно добавить ниже:

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

final может выглядеть так:

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
    }

Поскольку noStdlibLink = false, будет создан документ для унаследованной функции путем предоставления ссылки на kotlin-stdlib. вы можете найти дополнительную информацию здесь.

Я использовал dokka версии 0.9.17.

Вывод будет:

Задача :app:dokka АКТУАЛЬНО

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