生成 Kotlin 方法/类注释

Posted 2023-02-21

【中文标题】生成 Kotlin 方法/类注释

【英文标题】：Generating Kotlin method/class comments

【发布时间】：2016-10-27 04:27:54

【问题描述】：

您如何为您的方法/类生成 cmets？只需输入：

/**

在 IntelliJ IDEA 2016.1.3 中按 Enter 似乎不起作用

Dokka 好像已经取代了 KDoc，但是为什么 IntelliJ 没有支持呢？还是我错过了什么？

澄清：当输入 /** + enter 时，会生成：

/**
 *
 */

但我想知道为什么不添加 @param 和其他的生成（就像 IntelliJ 为 Java 所做的那样）。这些注释也用于记录 Kotlin 代码 (https://kotlinlang.org/docs/reference/kotlin-doc.html)

【问题讨论】：

/+*+*+ENTER 在 2016.1.3 为我生成/**\n * \n */。你能有一些导致问题的插件吗？

嗨，是的，对不起，我应该澄清它确实会生成，但它不会生成此处记录的@params/@return：kotlinlang.org/docs/reference/kotlin-doc.html 编辑：添加了对问题的澄清。

Generate KDoc for methods in android Studio的可能重复

【参考方案1】：

为了扩展@yole 的回答和@Charles A. 的评论，这里完整解释了创建KDocs 时的首选格式以及它与JavaDocs 的区别。

这里的 Kotlin 文档：

https://kotlinlang.org/docs/reference/coding-conventions.html#documentation-comments

...说：

一般来说，避免使用@param 和@return 标签。相反，将参数和返回值的描述直接合并到文档注释中，并在提及参数的任何地方添加指向参数的链接。仅当需要冗长的描述且不适合正文的流程时才使用@param 和@return。

避免这样做：

/**
 * Returns the absolute value of the given number.
 * @param number The number to return the absolute value for.
 * @return The absolute value.
 */
fun abs(number: Int) = ...

改为这样做：

/**
 * Returns the absolute value of the given [number].
 */
fun abs(number: Int) = ...

【参考方案2】：

@param 和其他标签不会生成，因为 Kotlin 的推荐文档样式是使用 [foo] 语法从文档注释文本中引用参数名称，而不是使用显式的 @param 标签来记录它们。您可以查看Kotlin standard library documentation 了解如何使用此样式。

【讨论】：

那为什么Documenting Kotlin Code页面有一个所有可用标签的列表呢？我真的错过了什么吗？

标签可用且受支持，但不推荐使用。

我必须要求您将我链接到尽可能详细地描述文档过程的文档。谢谢！因为从我在之前评论中发布的链接的外观来看，在我看来，这是 Kotlin 官方文档建议使用的。

@Daksh 对于它的价值，我发现该文档指的是here。

我检查了那个链接（“Kotlin 标准库”），但我没有看到任何关于注释函数的内容