Dokumentationskommentare werden nativ in Xcode unterstützt und erzeugen eine intelligent gerenderte Dokumentation in der Schnellhilfe (sowohl im Popover beim ⌥Klicken auf Symbole als auch im Quick Help Inspector)⌥⌘2 ).
Kommentare zur Symboldokumentation basieren jetzt auf derselben Markdown-Syntax, die auch von umfangreichen Spielplatzkommentaren verwendet wird. Daher kann vieles, was Sie auf Spielplätzen tun können, jetzt direkt in der Quellcodedokumentation verwendet werden.
Ausführliche Informationen zur Syntax finden Sie unter Markup-Formatierungsreferenz . Beachten Sie, dass es einige Diskrepanzen zwischen der Syntax für umfangreiche Spielplatzkommentare und Symboldokumentationen gibt. Auf diese wird im Dokument hingewiesen (z. B. können Blockzitate nur auf Spielplätzen verwendet werden).
Unten finden Sie ein Beispiel und eine Liste der Syntaxelemente, die derzeit für Kommentare zur Symboldokumentation funktionieren.
Aktualisierung
Xcode 7 Beta 4 ~ " - Throws: ..." als Listenelement der obersten Ebene hinzugefügt , das neben Parametern und Rückgabeversionen in der Schnellhilfe angezeigt wird.
Xcode 7 Beta 1 ~ Einige wichtige Änderungen an der Syntax mit Swift 2 - Dokumentationskommentare basieren jetzt auf Markdown (wie bei Spielplätzen).
Xcode 6.3 (6D570) ~ Einrückter Text wird jetzt als Codeblöcke formatiert, wobei nachfolgende Einrückungen verschachtelt werden. Es scheint nicht möglich zu sein, eine leere Zeile in einem solchen Codeblock zu belassen. Wenn Sie dies versuchen, wird der Text mit allen Zeichen am Ende der letzten Zeile angeheftet.
Xcode 6.3 beta ~ Inline-Code kann jetzt mithilfe von Backticks zu Dokumentationskommentaren hinzugefügt werden.
Beispiel für Swift 2
/// Text like this appears in "Description".
///
/// Leave a blank line to separate further text into paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// ---
///
/// More Stuff
/// ==========
///
/// Code
/// ----
///
/// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage:
///
/// // Create an integer, and do nothing with it
/// let myInt = 42
/// doNothing(myInt)
///
/// // Also notice that code blocks scroll horizontally instead of wrapping.
///
/// Links & Images
/// --------------
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// 
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
///
/// - parameters:
/// - int: A pointless `Int` parameter.
/// - bool: This `Bool` isn't used, but its default value is `false` anyway…
/// - throws: A `BadLuck` error, if you're unlucky.
/// - returns: Nothing useful.
func doNothing(int: Int, bool: Bool = false) throws -> String {
if unlucky { throw Error.BadLuck }
return "Totally contrived."
}
Syntax für Swift 2 (basierend auf Markdown )
Kommentarstil
Für die Erstellung von Dokumentationskommentaren werden sowohl ///(Inline-) als auch /** */(Block-) Kommentare unterstützt. Während ich persönlich den visuellen Stil von /** */Kommentaren bevorzuge , kann die automatische Einrückung von Xcode die Formatierung für diesen Kommentarstil beim Kopieren / Einfügen ruinieren, da führende Leerzeichen entfernt werden. Beispielsweise:
/**
See sample usage:
let x = method(blah)
*/
Beim Einfügen wird der Einzug des Codeblocks entfernt und nicht mehr als Code gerendert:
/**
See sample usage:
let x = method(blah)
*/
Aus diesem Grund verwende ich es im Allgemeinen ///und werde es für die restlichen Beispiele in dieser Antwort verwenden.
Blockelemente
Überschrift:
/// # My Heading
oder
/// My Heading
/// ==========
Unterüberschrift:
/// ## My Subheading
oder
/// My Subheading
/// -------------
Horizontale Regel:
/// ---
Ungeordnete (mit Aufzählungszeichen versehene) Listen:
/// - An item
/// - Another item
Sie können auch +oder *für ungeordnete Listen verwenden, es muss nur konsistent sein.
Geordnete (nummerierte) Listen:
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Codeblöcke:
/// for item in array {
/// print(item)
/// }
Eine Einrückung von mindestens vier Leerzeichen ist erforderlich.
Inline-Elemente
Schwerpunkt (kursiv):
/// Add like *this*, or like _this_.
Stark (fett):
/// You can **really** make text __strong__.
Beachten Sie, dass Sie keine Sternchen ( *) und Unterstriche ( _) für dasselbe Element mischen können .
Inline-Code:
/// Call `exampleMethod(_:)` to demonstrate inline code.
Links:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Bilder:
/// 
Die URL kann entweder eine Web-URL (mit "http: //") oder eine absolute Dateipfad-URL sein (ich kann anscheinend keine relativen Dateipfade zum Laufen bringen).
Die URLs für Links und Bilder können auch vom Inline-Element getrennt werden, um alle URLs an einem verwaltbaren Ort zu speichern:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Schlüsselwörter
Zusätzlich zur Markdown-Formatierung erkennt Xcode andere Markup-Schlüsselwörter, die in der Schnellhilfe prominent angezeigt werden. Diese Markup-Schlüsselwörter haben meistens das Format - <keyword>:(die Ausnahme istparameter , dass auch der Parametername vor dem Doppelpunkt enthalten ist), wobei das Schlüsselwort selbst mit einer beliebigen Kombination von Groß- / Kleinbuchstaben geschrieben werden kann.
Schlüsselwörter für Symbolabschnitte
Die folgenden Schlüsselwörter werden im Hilfe-Viewer unter dem Abschnitt "Beschreibung" und über dem Abschnitt "Deklariert in" als markante Abschnitte angezeigt. Wenn sie enthalten sind, wird ihre Reihenfolge wie unten gezeigt festgelegt, obwohl Sie sie in beliebiger Reihenfolge in Ihre Kommentare aufnehmen können.
Die vollständig dokumentierte Liste der Abschnittsschlüsselwörter und ihrer Verwendungszwecke finden Sie im Abschnitt Symbolabschnittsbefehle der Markup-Formatierungsreferenz .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
Alternativ können Sie jeden Parameter folgendermaßen schreiben:
/// - parameter <#parameter name#>:
Symbol Beschreibung Feldschlüsselwörter
Die folgende Liste von Schlüsselwörtern wird im Hauptteil des Abschnitts "Beschreibung" des Hilfe-Viewers als Fettdruck angezeigt . Sie werden in der Reihenfolge angezeigt, in der Sie sie schreiben, wie im Rest des Abschnitts "Beschreibung".
Die vollständige Liste stammt aus diesem ausgezeichneten Blog-Artikel von Erica Sadun. Weitere Informationen finden Sie in der vollständig dokumentierten Liste der Schlüsselwörter und ihrer Verwendungszwecke im Abschnitt "Befehle für Symbolbeschreibungsfelder" der Markup-Formatierungsreferenz .
Zuschreibungen:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Verfügbarkeit:
/// - since:
/// - version:
Ermahnungen:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Entwicklungsstand:
/// - bug:
/// - todo:
/// - experiment:
Implementierungsqualitäten:
/// - complexity:
Funktionale Semantik:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Querverweis:
/// - seealso:
Dokumentation exportieren
HTML-Dokumentation (die Apples eigene Dokumentation nachahmt) kann mithilfe von Jazzy , einem Open-Source-Befehlszeilenprogramm , aus Inline-Dokumentation generiert werden .
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Konsolenbeispiel aus diesem NSHipster-Artikel
