如何在kotlin kDoc中使用@link和@code

Question

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

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

Answer 1

@link并且@code在kDoc中不存在,但可以很容易地被内联标记替换.

来自KotlinDoc 链接到元素

内联标记

对于内联标记,KDoc使用常规Markdown语法,扩展为支持用于链接到代码中其他元素的简写语法.

链接到元素

要链接到另一个元素(类,方法,属性或参数),只需将其名称放在方括号中:

[foo]为此目的使用该方法.

如果要为链接指定自定义标签,请使用Markdown参考样式语法:

使用[this method][foo]用于这一目的.您还可以在链接中使用限定名称.请注意,与JavaDoc不同,限定名称始终使用点字符来分隔组件,甚至在方法名称之前:

使用[kotlin.reflect.KClass.properties]枚举类的属性.链接中的名称使用相同的规则进行解析,就好像在要记录的元素中使用了名称一样.特别是,这意味着如果您已将名称导入当前文件,则在KDoc注释中使用它时无需完全限定它.

请注意,KDoc没有任何语法来解析链接中的重载成员.由于Kotlin文档生成工具将函数的所有重载文档放在同一页面上,因此链接无需识别特定的重载函数.

Answer 2

For {@link SomeClass}in Java 映射到[SomeClass]Kotlin

因为{@code true}在 Java 中映射到 Kotlin 中的 `true`

Answer 3

看来我们应该只使用 markdown 超链接，而不使用任何特殊标签，例如@see或@link：

/**
 * This is a doc.
 *
 * See [this](https://google.com)
 * And [this](https://stackoverflow.com)
 */
fun myfun() {}

该文档在 IDE 中以以下方式呈现：

Answer 4

阿图尔给出的答案总体上是一个很好的提示，但结果是错误的。至少 IntelliJ IDEA 不会理解结果。Markdown 链接格式[]()在主评论文本中使用很好，但不适用于@see标签中的外部链接。对于那些，您需要与 Java 中相同的语法：

/**
 * Do something.
 *
 * @see <a href="/sf/ask/3163675931/">External links in kdoc</a>
 */

Answer 5

要引用方法，请使用类：

/**
 * When the configuration succeeds **[MyCallback.onConfigured]** is called.
 */
class MyClass(myCallback: MyCallback) {

使用变量/参数不起作用：

/**
 * When the configuration succeeds **[myCallback.onConfigured]** is called.
 */
class MyClass(myCallback: MyCallback) {

Answer 6

我在 Mac 上使用 Android Studio 3.5.2 对此进行了一些挣扎。这对我有用：

/**
* [Your fully-qualified class name.function name]
*/

如果我不使用完全限定名称 Kdoc 会抱怨它是一个未解析的引用。我无法弄清楚的是如何实际使用链接本身。为此，您需要按住 COMMAND 键（在 Mac 上），然后链接将处于活动状态。

Answer 7

如何留下课程链接的示例：

/**
 * [YourClass] Methods
 * */

也有方法调用

/**
 * [YourClass.someMothod] Methods
 * */

真实例子：

 /**
 * [BaseActivity] Methods
 * */
override fun initVars() {
    //Just Sample
}

/**
 * [MainContract.View] - Overrides
 * */
override fun handleConnectionMassage(isShow: Boolean) {
    //Just Sample
}

Answer 8

至于@code你应该使用Markdown 语法（因为 KDoc 是 Markdown 的扩展版本）：

要在 Markdown 中生成代码块，只需将代码块的每一行缩进至少 4 个空格或 1 个制表符。

/**
 * Some code sample:
 * 
 *    Set<String> s;
 *    System.out.println(s);
 */
class Scratch

Answer 9

您可以使用Java编写代码并将类转换为Kotlin。

/**
 * @see <a href="http://somelink.com">link</a>
 */
public class Some {
}

将被转换为

/**
 * @see [link](http://somelink.com)
 */
class Some