Was ist das neue Format der Dokumentation Kommentare in Swift 2? (XCode 7 Beta 3)

Question

Dort ist diese great article von Nate Cook und Matt Thompson, die das Format der Dokumentation Kommentare in Swift beschreibt.

Allerdings, seit Swift 2 in XCode 7 Beta scheinen einige Teile davon nicht mehr zu funktionieren. Zum Beispiel erzeugen :param: und :returns: nicht das gewünschte Ergebnis (sie werden einfach so wiedergegeben, wie sie sind).

Andere Teile scheinen weiterhin zu funktionieren, (d. H. Beide Arten von Kommentaren in /// ... oder /** ... */ Stil, Code-Blöcke, Listen), aber keine Möglichkeit, die Dokumentation in ähnliche Abschnitte wie die Kern-API zu markieren.

Weiß jemand, ob es eine Möglichkeit gibt, Methodenparameter hervorzuheben und Ergebnisse zurückzuliefern (was :param: und :returns: in der Vergangenheit getan hat) in Dokumentation Kommentare in Swift 2?

Answer 1

Wenn Sie nach Symbol Documentation Markup Syntax suchen, was bedeutet, wenn Sie die neue Syntax (Xcode 7) wissen möchten, um Dokumentation für Ihre Methoden mit Markdown zu schreiben, gibt es die Markup Formatting Reference auf der Apple-Website.

Hier ist, wie Sie definieren einen Baustein Kommentar:

/** 
    line of text with optional markup commands 
    … 
    line of text with optional markup commands 
*/ 

Und hier ist ein Beispiel eines Kommentars mit den wichtigsten tags:

/** 
    Just testing documentation using Markdown 
    - returns: Bool 
    - parameter param1:String 
    - parameter param2:String 
    - Throws: error lists 
*/ 

Und hier ist das kurze Format

/// line of text with optional markup commands 

Answer 2

What’s new in Xcode 7. gibt einen Hinweis

Abschriften Kommentare als Rich-Text in Schnellen Hilfe mit eingebetteten Bildern und Links angezeigt.

und die Xcode 7 Beta Release Notes Zustand:

Swift Dokumentation Kommentare verwenden, um eine Syntax auf dem Format Markdown basiert, so dass sie mit reichen Kommentare auf Spielplätzen ausrichten. (20180161)

gefolgt von einer kurzen Beschreibung.

Als Beispiel

/** 
    Repeats a string `times` times. 

    :param: str  The string to repeat. 
    :param: times The number of times to repeat `str`. 

    :returns: A new string with `str` repeated `times` times. 
*/ 
func repeatString(str: String, times: Int) -> String { 
    return join("", Array(count: times, repeatedValue: str)) 
} 

von http://nshipster.com/swift-documentation/ jetzt als

/// Repeats a string `times` times. 

/// - Parameters: 
///  - str:  The string to repeat. 
///  - times: The number of times to repeat `str`. 
/// - returns: A new string with `str` repeated `times` times. 
func repeatString(str: String, times: Int) -> String { 
    return Repeat(count: times, repeatedValue: str).joinWithSeparator("") 
} 

Oder mit mehrzeiligen Kommentar geschrieben werden würde:

/** 
    Repeats a string `times` times. 

    - Parameter str: The string to repeat. 
    - Parameter times: The number of times to repeat `str`. 
    - returns: A new string with `str` repeated `times` times. 
*/ 
func repeatString(str: String, times: Int) -> String { 
    return Repeat(count: times, repeatedValue: str).joinWithSeparator("") 
} 

Weitere Informationen zu Markdown finden

• https://en.wikipedia.org/wiki/Markdown
• http://daringfireball.net/projects/markdown/

und viel von

• Playground Markup Format for Comments

gilt auch Dokumentation Kommentare Inline.

Zum Beispiel könnten Sie

 
    **Important:** `times` must not be negative. 

wo "Wichtig" gemacht wird starke hinzufügen.

Answer 3

In Xcode 7 beta 4 eine Liste von Parametern nur wie folgt geschrieben werden kann: (. Dies ist ein Kommentar auf Martin R s Beitrag sein sollte, aber ich habe nicht den Ruf, dies zu tun)

- parameter str:  The string to repeat. 
- parameter times: The number of times to repeat `str`.