Verwendung von @link und @code in kotlin kDoc

Ich versuche eine Methode zu dokumentieren und zu verwenden @linkund @codewie in JavaDoc .

Ich weiß, dass es in Kotlin einen kDoc gibt, aber ich kann sie nicht finden oder zumindest etwas Ähnliches.

@linkund @codeexistiert nicht in kDoc, kann aber leicht durch Inline-Markup ersetzt werden .

von KotlinDoc Verknüpfen mit Elementen

Inline-Markup

Für Inline-Markups verwendet KDoc die reguläre Markdown- Syntax, die erweitert wurde, um eine Kurzschrift-Syntax für die Verknüpfung mit anderen Elementen im Code zu unterstützen.

Verknüpfen mit Elementen

Um eine Verknüpfung zu einem anderen Element (Klasse, Methode, Eigenschaft oder Parameter) herzustellen, setzen Sie den Namen einfach in eckige Klammern:

Verwenden Sie die Methode [foo]für diesen Zweck.

Wenn Sie eine benutzerdefinierte Bezeichnung für den Link angeben möchten, verwenden Sie die Markdown-Referenzsyntax:

Verwenden Sie [this method][foo]für diesen Zweck. Sie können auch qualifizierte Namen in den Links verwenden. Beachten Sie, dass qualifizierte Namen im Gegensatz zu JavaDoc immer das Punktzeichen verwenden, um die Komponenten zu trennen, noch vor einem Methodennamen:

Verwenden Sie [kotlin.reflect.KClass.properties]diese Option, um die Eigenschaften der Klasse aufzulisten. Namen in Links werden nach denselben Regeln aufgelöst, als ob der Name innerhalb des zu dokumentierenden Elements verwendet worden wäre. Dies bedeutet insbesondere, dass Sie einen Namen, der in die aktuelle Datei importiert wurde, nicht vollständig qualifizieren müssen, wenn Sie ihn in einem KDoc-Kommentar verwenden.

Beachten Sie, dass KDoc keine Syntax zum Auflösen überladener Mitglieder in Links hat. Da das Tool zur Generierung der Kotlin-Dokumentation die Dokumentation für alle Überladungen einer Funktion auf derselben Seite platziert, ist es nicht erforderlich, eine bestimmte überladene Funktion zu identifizieren, damit der Link funktioniert.

Sie können Ihren Code mit Java schreiben und die Klasse in Kotlin konvertieren.

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

wird konvertiert zu

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

Für {@link SomeClass}in Java Karten nach [SomeClass]in Kotlin

Für {@code true}in Java-Karten zu "true" in Kotlin

Die Antwort, die Artur gab, ist im Allgemeinen ein guter Hinweis, aber das Ergebnis ist falsch. Zumindest macht IntelliJ IDEA das Ergebnis nicht deutlich. Das verwendete Markdown-Link-Format []()ist im Hauptkommentartext in Ordnung, jedoch nicht für externe Links im @seeTag. Für diese benötigen Sie die gleiche Syntax wie in Java:

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

Ich hatte ein bisschen Probleme damit mit Android Studio 3.5.2 auf dem Mac. Das hat bei mir funktioniert:

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

Wenn ich nicht den vollqualifizierten Namen verwenden würde, würde sich Kdoc beschweren, dass es sich um eine ungelöste Referenz handelt. Was ich nicht herausfinden konnte, ist, wie man den Link selbst tatsächlich benutzt. Dazu müssen Sie die BEFEHLSTASTE (auf dem Mac) gedrückt halten, und dann sind die Links aktiv.

Verwenden Sie die Klasse, um auf eine Methode zu verweisen :

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

Die Verwendung einer Variablen / eines Parameters funktioniert nicht :

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

Für die @codesollten Sie die Markdown-Syntax verwenden (da KDoc eine erweiterte Version von Markdown ist):

Um einen Codeblock in Markdown zu erstellen, rücken Sie einfach jede Zeile des Blocks um mindestens 4 Leerzeichen oder 1 Tabulator ein.

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