标签: kdoc

对于两种给定的方法:

/**
* 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并不是那么好,因为如果你更新其中一个,很有可能第二个意外地过时.

我正在写一个Kotlin图书馆.在其中一个课程中,我有以下内容:

class SessionWrapper {

    /**
     * The time in milliseconds after which the session will expire.
     */
    var expiryTime = DEFAULT_EXPIRY_TIME
        get() {
            mainThreadCheck()
            return field
        }
        set(value) {
            mainThreadCheck()
            field = value
            updateExpiry(value) <<< THIS ONE
        }

    ...
}

但是,如果他们修改了(即调用setter),则updateExpiry(long)有一个对客户端应该是透明的行为.SessionWrapperexpiryTime

现在,对于Kotlin项目,这不会是一个问题,因为我可以将额外的KDoc添加到expiryTime属性本身,并且它不会感觉不合适:

    /**
     * The time in milliseconds after which the session will expire.
     *
     * Updating the expiry time after the session is started does x,
     * the listeners will receive y.
     * …

我在这里看到过,这里和那里引用了KDoc,它是Kotlin的JavaDoc实用程序.

但是,我找不到任何关于如何使用它的文档,更不用说如何自定义它或将它集成到Maven或Gradle中.

我知道Kotlin API文档是使用KDoc生成的,因为页面源具有以下HTML注释:<!-- Generated by kdoc on Sun Jul 06 20:27:33 UTC 2014 -->

那么,有没有关于如何使用KDoc的文档？

我应该在哪里将Javadoc用于Kotlin数据类中的属性？

换句话说,如何在Kotlin中编写以下Java代码:

/**
 * Represents a person.
 */
public class Person {
    /**
     * First name. -- where to place this documentation in Kotlin?
     */
    private final String firstName;
    /**
     * Last name. -- where to place this documentation in Kotlin?
     */
    private final String lastName;

    // a lot of boilerplate Java code - getters, equals, hashCode, ...
}

在Kotlin看起来像这样:

/**
 * Represents a person.
 */
data class Person(val firstName: String, val lastName: String)

但是在哪里放置属性的文档？

我应该在哪里对 Kotlin 源文件发表评论？

类和其他对象具有 KDoc：

/**
 * Summary
 *
 * Rest of documentation goes here.
 */
class A {
    ...
}

但是我应该把这样的东西放在哪里？

// This file contains constants shared between frontend and backend.
// Make sure not to use any JVM- or JS-specific import.
// ...

package声明之前？之后呢？我应该使用 KDoc 注释/块注释/行注释吗？

有没有既定的约定？

我曾经像这样引用 Java Doc 中的方法：

/**
 * @see com.myapp.view.fragment.PlaybackControlFragment#onPlaybackStateChanged
 */

我不知道如何在 kotlin 中引用相同的方法？

该部分com.myapp.view.fragment.PlaybackControlFragment已链接，但方法名称不可点击和链接。

什么是正确的语法？

考虑这个 Kotlin 类的类注释：

/**
 * This class has two methods, one that takes one parameters ([foo]),
 * and another one that takes two parameters ([foo]).
 **/
class Clazz {
    /* Foo with one. */
    fun foo(a: Int) {  }

    /* Foo with two. */
    fun foo(a: Int, b: Int) {  }
}

我希望第二个链接指向第二个函数（带有两个参数的函数）。

这在 Kotlin 文档语言中是可能的吗？

我有带有 KDoc 的 Kotlin 类，例如：

abstract class Something {
  /** # Documentation */
  abstract fun someFun()
}

这个类由 Kotlin 和 Java 类扩展。KDoc 由 Kotlin 类正确继承。在子类中的 Intellij 中单击 Ctrl+Q 时会显示 KDoc。但是，如果子类是用 Java 编写的，则它不起作用。在这种情况下，不会继承 KDoc。

如何在 Java 中继承 KDoc？

在 JavaDoc 中，您可以添加如下图像：

/**
 * ...The following legend explains these diagrams:
 * <img width="640" height="577" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.png" alt="">
 */
public class Test {
}

我如何在 Kotlin Kdoc 中实现同样的目标？

KDoc 包含一些包和 Kotlin 文件的链接，但我实际上看不到这样的包和文件

文档窗口截图

我查看了 Google Maven 存储库，希望发现我只是没有在我的 中包含一些包build.gradle，但也没有这样的工件