I commenti sulla documentazione sono supportati in modo nativo in Xcode, producendo una documentazione resa in modo intelligente in Guida rapida (sia nella popover quando si fa clic sui ⌥simboli, sia nella finestra di ispezione Guida rapida ⌥⌘2).
I commenti sulla documentazione dei simboli ora si basano sulla stessa sintassi Markdown utilizzata dai ricchi commenti sui campi da gioco, quindi molto di ciò che è possibile fare nei campi da gioco può ora essere utilizzato direttamente nella documentazione del codice sorgente.
Per i dettagli completi sulla sintassi, consultare Markup Formatting Reference . Si noti che ci sono alcune discrepanze tra la sintassi per i commenti sui giochi e la documentazione dei simboli; questi sono indicati nel documento (ad es. le virgolette di blocco possono essere utilizzate solo nei campi da gioco).
Di seguito è riportato un esempio e un elenco degli elementi di sintassi che attualmente funzionano per i commenti sulla documentazione dei simboli.
aggiornamenti
Xcode 7 beta 4 ~ " - Throws: ..." aggiunto come elemento di elenco di livello superiore che viene visualizzato accanto ai parametri e restituisce le descrizioni nella Guida rapida.
Xcode 7 beta 1 ~ Alcune modifiche significative alla sintassi con Swift 2 - commenti sulla documentazione ora basati su Markdown (lo stesso dei campi da gioco).
Xcode 6.3 (6D570) ~ Il testo con rientro è ora formattato come blocchi di codice, con i rientri successivi nidificati. Non sembra possibile lasciare una riga vuota in un tale blocco di codice - provando a farlo si ottiene che il testo venga incollato alla fine dell'ultima riga con qualsiasi carattere al suo interno.
Xcode 6.3 beta ~ Il codice incorporato può ora essere aggiunto ai commenti della documentazione usando i backtick.
Esempio per 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."
}
Sintassi per Swift 2 (basato su Markdown )
Stile di commento
Entrambi ///(in linea) e /** */commenti (blocco) di stile sono supportati per la produzione di commenti di documentazione. Mentre personalmente preferisco lo stile visivo dei /** */commenti, il rientro automatico di Xcode può rovinare la formattazione per questo stile di commento durante la copia / incolla in quanto rimuove i primi spazi bianchi. Per esempio:
/**
See sample usage:
let x = method(blah)
*/
Quando si incolla, il rientro del blocco di codice viene rimosso e non viene più visualizzato come codice:
/**
See sample usage:
let x = method(blah)
*/
Per questo motivo, generalmente lo uso ///e lo userò per il resto degli esempi in questa risposta.
Block Elements
Intestazione:
/// # My Heading
o
/// My Heading
/// ==========
Sottotitolo:
/// ## My Subheading
o
/// My Subheading
/// -------------
Regola orizzontale:
/// ---
Elenchi non ordinati (puntati):
/// - An item
/// - Another item
Puoi anche usare +o *per elenchi non ordinati, deve solo essere coerente.
Elenchi ordinati (numerati):
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Blocchi di codice:
/// for item in array {
/// print(item)
/// }
È richiesto un rientro di almeno quattro spazi.
Inline Elements
Enfasi (corsivo):
/// Add like *this*, or like _this_.
Forte (grassetto):
/// You can **really** make text __strong__.
Nota che non puoi mescolare asterischi ( *) e caratteri di sottolineatura ( _) sullo stesso elemento.
Codice incorporato:
/// Call `exampleMethod(_:)` to demonstrate inline code.
link:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Immagini:
/// 
L'URL può essere un URL Web (usando "http: //") o un URL percorso file assoluto (non riesco a far funzionare i percorsi file relativi).
Gli URL per collegamenti e immagini possono anche essere separati dall'elemento inline per mantenere tutti gli URL in un posto gestibile:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
parole
Oltre alla formattazione Markdown, Xcode riconosce altre parole chiave di markup da mostrare in primo piano nella Guida rapida. Queste parole chiave di markup assumono principalmente il formato - <keyword>:(l'eccezione è parameter, che include anche il nome del parametro prima dei due punti), dove la parola chiave stessa può essere scritta con qualsiasi combinazione di caratteri maiuscoli / minuscoli.
Parole chiave della sezione simboli
Le seguenti parole chiave vengono visualizzate come sezioni prominenti nel visualizzatore della guida, sotto la sezione "Descrizione" e sopra la sezione "Dichiarato in". Se incluso, il loro ordine viene corretto come mostrato di seguito anche se puoi includerli nell'ordine che preferisci nei tuoi commenti.
Consulta l'elenco completo delle parole chiave della sezione e dei loro usi previsti nella sezione Comandi della sezione simboli del Riferimento per la formattazione del markup .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
In alternativa, puoi scrivere ogni parametro in questo modo:
/// - parameter <#parameter name#>:
Simbolo Descrizione Parole chiave del campo
Il seguente elenco di parole chiave viene visualizzato come intestazioni in grassetto nel corpo della sezione "Descrizione" del visualizzatore della guida. Appariranno nell'ordine in cui li scrivi, come nel resto della sezione "Descrizione".
Elenco completo parafrasato da questo eccellente articolo di blog di Erica Sadun. Vedi anche l'elenco completo delle parole chiave e dei loro usi previsti nella sezione Comandi dei campi Descrizione simbolo del Riferimento per la formattazione del markup .
Attribuzioni:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Disponibilità:
/// - since:
/// - version:
ammonizioni:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Stato di sviluppo:
/// - bug:
/// - todo:
/// - experiment:
Qualità di attuazione:
/// - complexity:
Semantica funzionale:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Riferimento incrociato:
/// - seealso:
Esportazione della documentazione
La documentazione HTML (progettata per imitare la documentazione di Apple) può essere generata dalla documentazione in linea utilizzando Jazzy , un'utilità da riga di comando open source.
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Esempio di console tratto da questo articolo di NSHipster
