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

Question

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

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

Answer 1

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

Inline Markup

For inline markup, KDoc uses the regular Markdown syntax, extended to support a shorthand syntax for linking to other elements in the code.

Linking to Elements

To link to another element (class, method, property or parameter), simply put its name in square brackets:

Use the method [foo] for this purpose.

If you want to specify a custom label for the link, use the Markdown reference-style syntax:

Use [this method][foo] for this purpose. You can also use qualified names in the links. Note that, unlike JavaDoc, qualified names always use the dot character to separate the components, even before a method name:

Use [kotlin.reflect.KClass.properties] to enumerate the properties of the class. Names in links are resolved using the same rules as if the name was used inside the element being documented. In particular, this means that if you have imported a name into the current file, you don't need to fully qualify it when you use it in a KDoc comment.

Note that KDoc does not have any syntax for resolving overloaded members in links. Since the Kotlin documentation generation tool puts the documentation for all overloads of a function on the same page, identifying a specific overloaded function is not required for the link to work.

Answer 2

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

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

将转换为

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

Answer 3

给出的提示总体上是一个很好的提示，但结果是错误的。至少 IntelliJ IDEA 不会理解结果。使用 []() 的降价 link 格式在主要评论文本中很好，但不是对于 @see 标签中的外部 links .对于那些，您需要与 Java:

中相同的语法

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

Answer 4

我在 Mac 上使用 Android Studio 3.5.2 遇到了一些问题。这对我有用：

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

如果我不使用完全限定名称，Kdoc 会抱怨这是一个未解析的引用。我想不通的是如何实际使用 link 本身。为此，您需要按住 COMMAND 键（在 Mac 上）然后 links 将被激活。

Answer 5

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

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab.

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

Answer 6

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

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

Answer 7

要引用方法，请使用class:

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

使用 variable/parameter 不起作用:

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

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

看来我们应该只使用没有任何特殊标签的降价超链接，例如 @see 或 @link:

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

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

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

How to use @link and @code in kotlin kDoc

documentation

kotlin

kdoc