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

Question

我正在尝试记录一种方法并尝试使用@link 和@code，如JavaDoc。

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

Answer 1

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

来自 KotlinDoc Linking to Elements

内联标记

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

链接到元素

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

为此使用方法[foo]。

如果你想指定一个自定义 链接标签，使用 Markdown 引用样式语法：

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

使用[kotlin.reflect.KClass.properties]枚举属性 班上。链接中的名称使用相同的规则解析，就好像 在记录的元素内使用了名称。特别是，这 意味着如果您已将名称导入当前文件，您 当您在 KDoc 评论中使用它时，不需要完全限定它。

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

Answer 2

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

Java 中的 {@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

answer that 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 syntax（因为KDoc是Markdown的扩展版本）：

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

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

Answer 8

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

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

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

Answer 9

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

/**
 * [YourClass] Methods
 * */

还有方法调用

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

---

真实例子：

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

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