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

Question

我正在尝试记录一个方法并尝试在JavaDoc@link中使用and 。@code

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

Answer 1

@link并且@code在 kDoc 中不存在，但可以很容易地被Inline Markup替换。

从 KotlinDoc链接到元素

内联标记

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

链接到元素

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

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

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

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

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

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

Answer 2

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

Java 中的for{@code true}映射到 Kotlin 中的 `true`

Answer 3

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

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

将转换为

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

Answer 4

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

/**
 * Do something.
 *
 * @see <a href="https://stackoverflow.com/q/45195370/2621917">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

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

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

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

Answer 8

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

/**
 * [YourClass] Methods
 * */

也有方法调用

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

---

真实例子：

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

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

Answer 9

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

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

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