标签: kdoc

我正在尝试记录一个方法并尝试使用@link和@code在JavaDoc中一样.

我知道在kotlin有一个kDoc,但我找不到它们或至少有类似的东西.

在Java的Javadoc中,有一种方法可以使用{@inheritDoc}标记在子类中继承方法的文档.

有没有办法在Kotlin的KDoc中做同样的事情？

基本上,我想做的是以下内容:

abstract class Base {
    /**
     * Some KDoc documentation here.
     */
    abstract fun foo()
}

class Derived: Base() {
    /**
     * Here is all the documentation from Base#foo's KDoc inherited.
     *
     * And here goes something more in addition.
     */
    override fun foo() { /* ... */ }
}

如何在Kotlin的默认文档工具KDoc中插入代码片段？

在Java中,我可以使用以下内容:

/**
 * Example usage:
 *
 * <pre>
 * <code>&#64;JavaAnnotation
 * public void foo() {
 *     // Code
 * }
 * </code>
 * </pre>
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface JavaAnnotation {}

Kotlin似乎没有相应的东西.我尝试使用Markdown,但在行结束后插入2个空格不会换行.

给出以下代码

fun example() {}

fun example(name: String) {}

我如何参考特定功能？即example()或example(String)？

使用[example]我无法指定我想要的功能.

假设我们有这样的文件字符串

/** retrieve a state of the service
* <br/> HTTP code 200 - normal state
* <br/> HTTP code 403 - some recoverable state:
const val SERVICE_STATE = "servicestate" */

这里有几个<br/>,我用来打破一条线,就像我在java中做的那样,但AndroidStudio的输出(在InteliJIdea中看起来相同)是

使用java,它被正确解析和显示:

/** retrieve a state of the service
 * <br/> HTTP code 200 - normal state
 * <br/> HTTP code 403 - some recoverable state */
public static final String SERVICE_STATE = "servicestate";

我能以某种方式与kotlin和IntelijIdea达到同样的目的,也许kotlin可以在KDoc中打破这条线吗？

我在Kotlin官方参考中找到了记录Kotlin代码的页面.

然而,我无法找到如何突出文档的某些部分,例如,将其标记为斜体或粗体.

我是Kotlin的新手,来自Java,以前只使用过我们使用的JavaDoc <i>和<b>HTML标签来突出文档中的部分.

对于两种给定的方法:

/**
* Adds a [DataItem] to the Android Wear network. The updated item is synchronized across all devices.
*/
fun putItem(){ .... }

/**
* "same KDOC here with above"
*/
fun putItem(putRequest: PutDataRequest){ .... }

有没有可能复制/链接第二种方法的文档与第一种方法相同？

手动复制粘贴KDOC并不是那么好,因为如果你更新其中一个,很有可能第二个意外地过时.

我如何将（经过测试的、非陈旧的）代码示例包含到 Dokka 包文档中？

更具体地说，假设我的以下配置中有此配置build.gradle.kts：

withType<DokkaTask> {
    outputFormat = "html"
    outputDirectory = "$buildDir/documentation"
    includes = listOf("packageDocumentation.md")
    samples = listOf("$rootDir/src/test/kotlin/some/project/TheSamples.kt")
}

然后是一些测试代码：

package some.project
import org.junit.jupiter.api.Test

class TheSamples {
    @Test
    fun helloWorldSample() {
        println("hello, world")
    }
}

还有一个包文档 Markdown 文件：

# Package some.project

This is the documentation for some package.

@sample some.project.TheSamples#helloWorldSample

，如何将println(...)-part包含到文档中？当前版本的 Dokka 是否完全支持它？

交换#的.或更换@sample由@includeFunction什么也没做。

此外：

• 这是一个相关的问题，将近两年没有回答。
• 这是 2012 年的一些讨论，现在几乎完全由死链接组成。

有没有办法为 Kotlin 文件添加一段顶级 KDoc？

由于 Kotlin 在单个文件中支持多个变量、函数、类等，因此将文件作为一个整体来记录是有意义的。但是，记录 Kotlin 代码 - Kotlin 编程语言似乎没有任何说明。

背景

经过大量的研究和尝试，并寻求帮助，我已经成功地在 Jitpack 上使用 maven 发布了一个私有的 Github 存储库（写在这里）。

所以，目前我放在 Jitpack 存储库中的文件只是这些：

• jitpack.yml - 告诉使用哪些文件
• library-release.aar -（混淆的）代码本身
• pom-default.xml - 依赖项和其他一些配置。

问题

虽然依赖问题和 AAR 文件本身很好，我可以使用该库，但我注意到我找不到一种方法将我在那里编写的内容作为 KDoc（如 JavaDocs，但适用于 Kotlin）提供给使用它的任何人。

我试过的

除了各种gradle任务，我还尝试了Android Studio本身的简单操作来制作。由于没有提到 KDoc，我使用Tools->Generate JavaDocs代替。

可悲的是，它告诉我没有，而且确实是在这里报道的。

但即使它确实成功了，我也不知道如何将它与其他文件一起发布。

问题

我希望这是可能的，但是如何在 Jitpack 上使用 maven 生成和公开 KDoc？