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

77

我正在尝试记录一种方法，并试图像JavaDoc中那样使用@link和。@code

我知道在Kotlin中有一个kDoc，但我找不到它们或至少找不到类似的东西。

documentation kotlin kdoc

— 感到惊讶
source

我是用/*的，而不是/**...

— 奔巴特沃斯

116

@link并且@code在kDoc中不存在，但可以轻松地由Inline Markup替换。

从KotlinDoc链接到Elements

内联标记

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

链接到元素

要链接到另一个元素（类，方法，属性或参数），只需将其名称放在方括号中：

[foo]为此使用方法。

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

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

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

请注意，KDoc没有用于解析链接中重载成员的任何语法。由于Kotlin文档生成工具将函数所有重载的文档放在同一页上，因此链接正常工作不需要识别特定的重载函数。

— 感到惊讶
source

13

对于任何努力解决非静态方法的人，您不能只做[class.methodName]，而必须做[full_package_location.methodName]

— hmac

4

@hmac是正确的，但是您也可以将方法名称添加到导入中。IDE不会为您提供intellisense选项来为您执行此操作，但是它确实起作用。

— 戴夫

您先生是救命先生@hmac

— ericn

如何应用于外部链接？

— desgraci '20

右键单击方法名称，然后选择第二个选项“复制参考”，终于得到了正确的链接。我不确定是否会有所作为，但是我的方法是对象内部的JVM静态方法。

— beyondtheteal

19

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

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

将转换为

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

— 阿图尔·杜姆切夫（Artur Dumchev）
source

我在这个要点中尝试了这种方法。但是，该链接未发生格式化。

— 亚当·赫维兹

1

这么晚才回复很抱歉。看来您的文件格式错误。例如，您应该在// ** * /而不是您可能在ContentRepository文件中使用的“ //”来编写文档。要检查一切是否正常，可以尝试我提供的示例。

— Artur Dumchev

我在@Artur Dumchev上方的要点中更新了格式。您的示例使用Java，而我的使用Kotlin，这就是为什么我不确定确切格式的原因。谢谢！

— 亚当·赫维兹

格式化无效，我们无法像Java中那样导航到Kotlin中的链接。@AdamHurwitz你能使它工作吗？

— SjDev

@SjNerd-负面

— 亚当·赫维兹

15

对于{@link SomeClass}Java映射到[SomeClass]Kotlin

{@code true}在Java中，对于Kotlin中的映射为`true`

— Aryeetey所罗门Aryeetey
source

10

总的来说，阿图尔给出的答案是一个很好的暗示，但结果是错误的。至少IntelliJ IDEA不会取消结果。[]()在主注释文本中使用markdown链接格式是可以的，但对于标记中的外部链接则不能@see。对于这些，您需要与Java中相同的语法：

/**
 * Do something.
 *
 * @see <a href="https://stackoverflow.com/q/45195370/2621917">External links in kdoc</a>
 */

— 迈克尔·皮菲尔
source

7

我在Mac上的Android Studio 3.5.2上为此付出了一些努力。这为我工作：

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

如果我不使用全限定名，则Kdoc会抱怨这是一个未解决的引用。我不知道是如何实际使用链接本身。为此，您需要按住COMMAND键（在Mac上），然后链接将处于活动状态。

— 萨斯克
source

7

要引用方法，请使用类：

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

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

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

— hb0
source

2

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

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

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

— 5555
source