web-dev-qa-db-ja.com

kotlin kDocで@linkおよび@codeを使用する方法

JavaDoc のように、メソッドを文書化し、@linkおよび@codeを使用しようとしています。

私はkotlinに kDoc があることを知っていますが、それらまたは少なくとも類似のものを見つけることができません。

documentationkotlinkdoc
36
humazed

@linkおよび@codeはkDocには存在しませんが、 インラインマークアップ で簡単に置き換えることができます。

kotlinDocから 要素へのリンク

インラインマークアップ

インラインマークアップの場合、KDocは通常の Markdown 構文を使用します。この構文は、コード内の他の要素にリンクするための簡略構文をサポートするように拡張されています。

要素へのリンク

別の要素（クラス、メソッド、プロパティ、またはパラメーター）にリンクするには、その名前を角かっこで囲みます。

この目的には、メソッド[foo]を使用します。

リンクのカスタムラベルを指定する場合は、Markdown参照スタイルの構文を使用します。

この目的には[this method][foo]を使用します。リンクで修飾名を使用することもできます。 JavaDocとは異なり、修飾名では、メソッド名の前であっても、常にドット文字を使用してコンポーネントを区切ります。

[kotlin.reflect.KClass.properties]を使用して、クラスのプロパティを列挙します。リンク内の名前は、文書化されている要素内で名前が使用された場合と同じルールを使用して解決されます。特に、これは、現在のファイルに名前をインポートした場合、KDocコメントで使用するときに完全に修飾する必要がないことを意味します。

KDocには、リンク内のオーバーロードされたメンバーを解決するための構文がないことに注意してください。 Kotlinドキュメント生成ツールは関数のすべてのオーバーロードのドキュメントを同じページに配置するため、リンクが機能するために特定のオーバーロードされた関数を識別する必要はありません。

71
humazed

Javaを使用してコードを記述し、クラスをKotlinに変換できます。

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

に変換されます

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

Arturの答え は一般的には良いヒントですが、結果は間違っています。少なくともIntelliJ IDEAは結果を不満にしません。[]()を使用したマークダウンリンク形式はメインのコメントテキストでは問題ありませんが、not@seeタグ内の外部リンクの場合は、Javaの場合と同じ構文が必要です。

/**
 * Do something.
 *
 * @see <a href="https://stackoverflow.com/q/45195370/2621917">External links in kdoc</a>
 */
2
Michael Piefel