Viele Sprachen unterstützen Dokumentationskommentare , um einen Generator (wie javadocoder Sauerstoff) zu ermöglichen ) durch Parsen desselben Codes generieren kann.

Hat Swift eine solche Dokumentationskommentarfunktion?

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:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - 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:

/// ![Alt Text](http://www.example.com/alt-image.jpg)

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

Hier sind einige Dinge, die für die Dokumentation von schnellem Code in Xcode 6 funktionieren. Es ist sehr fehlerhaft und empfindlich gegenüber Doppelpunkten, aber es ist besser als nichts:

class Foo {

    /// This method does things.
    /// Here are the steps you should follow to use this method
    ///
    /// 1. Prepare your thing
    /// 2. Tell all your friends about the thing.
    /// 3. Call this method to do the thing.
    ///
    /// Here are some bullet points to remember
    ///
    /// * Do it right
    /// * Do it now
    /// * Don't run with scissors (unless it's tuesday)
    ///
    /// :param: name The name of the thing you want to do
    /// :returns: a message telling you we did the thing
    func doThing(name : String) -> String {
        return "Did the \(name) thing";
    }
}

Das Obige wird in der Schnellhilfe wie erwartet mit formatierten numerischen Listen, Aufzählungszeichen, Parameter- und Rückgabewertdokumentation gerendert.

Nichts davon ist dokumentiert - reichen Sie ein Radar ein, um ihnen weiterzuhelfen.

Neu in Xcode 8 können Sie eine solche Methode auswählen

func foo(bar: Int) -> String { ... }

Drücken Sie dann command+ option+/ oder wählen Sie "Struktur" - "Dokumentation hinzufügen" aus dem Xcode-Menü "Editor". Daraufhin wird die folgende Kommentarvorlage für Sie generiert:

/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>

Swift enthält "///" Kommentarbehandlung (obwohl wahrscheinlich noch nicht alles).

Schreiben Sie so etwas wie:

/// Hey!
func bof(a: Int) {

}

Dann klicken Sie bei gedrückter Wahltaste auf den Funktionsnamen und voilà :)

Ich kann bestätigen, dass ShakenManChild eine Lösung für Menschen bereitgestellt hat

Stellen Sie einfach sicher, dass Sie eine leere Zeile unter der Beschreibung haben!

Ja. Basis gemeinsam (ich habe Schnipsel dafür mit Obj-C-Äquivalent gemacht)

Ziel c:

/**
 @brief <#Short description - what it is doing#>

 @discussion <#Description#>

 @param  <#paramName#> <#Description#>.

 @return <#dataType#> <#Description#>.
 */

Schnell

/**
<#Short inline description - what it is doing#>

<#Description#>

:param:  <#paramName#> <#Description#>.

:returns: <#dataType#> <#Description#>.
*/

Wenn Sie nur Swift verwenden, ist Jazzy einen Blick wert.

https://github.com/realm/jazzy

Ich habe etwas Interessantes gefunden, indem ich in der Xcode-Binärdatei gegraben habe. Dateien mit dem Ende .swiftdoc. Es enthält definitiv Dokumente, da diese Dateien die Dokumente für die Swift UIKit / Foundation-API enthalten. Leider scheint es sich um ein proprietäres Dateiformat zur Verwendung im Documentation Viewer in Xcode zu handeln.

Im Xcode-Editor -> Struktur -> Dokumentation hinzufügen.

Jazzy kann dabei helfen, eine schöne Dokumentation im Apfelstil zu erstellen. Hier ist eine Beispiel-App mit Details zur schnellen Verwendung und Konfiguration.

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy

Vielleicht ist es eine gute Idee, ein Auge auf AppleDoc oder Apples eigenen HeaderDoc zu werfen, der nicht sehr erkannt wird. Ich kann immer noch einige HeaderDoc-Hinweise im 10.9 Mavericks-Terminal (headerdoc2html) finden.

Ich empfehle, das neueste " Was ist neu in Xcode " zu lesen * (nicht sicher, ob es noch unter NDA ist) * Der Link verweist auf die Xcode 5.1-Version, die auch Infos zu HeaderDoc enthält.

Ab Xcode 5.0 werden strukturierte Kommentare von Doxygen und HeaderDoc unterstützt.

Quelle