生成 Kotlin 方法/类注释 [英] Generating Kotlin method/class comments

问题描述

你如何为你的方法/类生成注释?只需输入:

How do you generate comments for your methods/classes? Simply typing:

/**

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

And pushing enter does not seem to work in IntelliJ IDEA 2016.1.3

似乎 Dokka 已经取代了 KDoc，但为什么 IntelliJ 中没有支持?还是我遗漏了什么?

It seems like Dokka has superseded KDoc, but why is there no support in IntelliJ? Or am I missing something?

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

Clarification: when typing in /** + enter, this gets generated:

/**
 *
 */

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

But I'm wondering why the generation of @param and others aren't added (like IntelliJ does for Java). These annotations are used for documenting Kotlin code as well (https://kotlinlang.org/docs/reference/kotlin-doc.html)

推荐答案

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

To expand on @yole's answer and @Charles A.'s comment, here is a full explanation of the preferred format when creating KDocs and how it differs from JavaDocs.

此处的 Kotlin 文档:

The Kotlin documentation here:

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

...说:

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

Generally, avoid using @param and @return tags. Instead, incorporate the description of parameters and return values directly into the documentation comment, and add links to parameters wherever they are mentioned. Use @param and @return only when a lengthy description is required which doesn't fit into the flow of the main text.

避免这样做:

/**
 * 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) = ...

这篇关于生成 Kotlin 方法/类注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！