it-swarm.com.de

Verwendung von @link und @code in kotlin kDoc

Ich versuche, eine Methode zu dokumentieren und versuche, @link und @code wie in JavaDoc zu verwenden.

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

24
humazed

@link und @code sind in kDoc nicht vorhanden, können jedoch leicht durch Inline Markup ersetzt werden.

von KotlinDoc Verknüpfung zu Elementen

Inline Markup

Für Inline-Markup verwendet KDoc die reguläre Markdown -Syntax, erweitert um unterstützt eine Abkürzungssyntax für die Verknüpfung mit anderen Elementen im Code.

Verknüpfen mit Elementen

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

Verwenden Sie dazu die Methode [foo].

Wenn Sie eine benutzerdefinierte .__ angeben möchten. Beschriftung für den Link verwenden Sie die Markdown-Referenzstil-Syntax:

Verwenden Sie dazu [this method][foo]. Sie können auch qualifiziertes .__ verwenden. Namen in den Links. Beachten Sie, dass qualifizierte Namen im Gegensatz zu JavaDoc immer .__ sind. Verwenden Sie das Punktzeichen, um die Komponenten zu trennen, sogar vor einer Methode Name:

Verwenden Sie [kotlin.reflect.KClass.properties], um die Eigenschaften von .__ aufzulisten. die Klasse. Namen in Verknüpfungen werden nach den gleichen Regeln aufgelöst wie bei der Der Name wurde innerhalb des zu dokumentierenden Elements verwendet. Insbesondere diese bedeutet, dass, wenn Sie einen Namen in die aktuelle Datei importiert haben, Sie Es muss nicht vollständig qualifiziert werden, wenn Sie es in einem KDoc-Kommentar verwenden.

Beachten Sie, dass KDoc keine Syntax für das Auflösen von überladenem .__ hat. Mitglieder in Links. Da setzt das Kotlin-Dokumentationserstellungstool die Dokumentation für alle Überladungen einer Funktion auf derselben Seite, Das Identifizieren einer bestimmten überladenen Funktion ist für das .__ nicht erforderlich. Link zur Arbeit.

53
humazed

Das Antwort von Artur ist im Allgemeinen ein guter Hinweis, aber das Ergebnis ist falsch. Zumindest IntelliJ IDEA macht das Ergebnis nicht schlecht. Das Markdown-Link-Format unter Verwendung von []() ist im Hauptkommentartext in Ordnung, aber nicht für externe Links im @see Etikett. 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>
 */
2
Michael Piefel

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

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

wird in konvertiert

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