Una delle nuove funzionalità di Xcode 5 è la possibilità di documentare il proprio codice con una sintassi di commento speciale. Il formato è simile a doxygen, ma sembra supportare solo un sottoinsieme di tali funzionalità .

Quali comandi sono supportati e quali no?
Qualcuno dei loro usi differisce dal doxygen?

Ecco un esempio di tutte le opzioni che ho trovato a partire da Xcode 5.0.2

Quello è stato generato con questo codice:

/** First line text.

 Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!

 @a Italic text @em with @@a or @@em.

 @b Bold text with @@b.

 @p Typewritter font @c with @@p or @@c.

 Backslashes and must be escaped: C:\\foo.

 And so do @@ signs: user@@example.com

 Some more text.
 @brief brief text
 @attention attention text
 @author author text
 @bug bug text
 @copyright copyright text
 @date date text
 @invariant invariant text
 @note note text
 @post post text
 @pre pre text
 @remarks remarks text
 @sa sa text
 @see see text
 @since since text
 @todo todo text
 @version version text
 @warning warning text

 @result result text
 @return return text
 @returns returns text


 @code
// code text
while (someCondition) {
    NSLog(@"Hello");
    doSomething();
}@endcode
 Last line text.

 @param param param text
 @tparam tparam tparam text
 */
- (void)myMethod {}

Appunti:

• I comandi devono essere in una /** block */, /*! block */o prefisso ///o //!.
• I comandi funzionano con il prefisso@ ( stile headerdoc ) o \( stile doxygen ). (Ie @bed \bentrambi fanno la stessa cosa.)
• I comandi di solito vengono prima dell'elemento che stanno descrivendo. (Vale a dire, se si sta cercando di documentare una proprietà, il commento deve venire prima del @propertytesto.) Possono venire dopo, sulla stessa linea, con /*!<, /**<, //!<, ///<.
• È possibile aggiungere documentazione a classi, funzioni, proprietà e variabili .
• Tutti questi comandi vengono visualizzati in testo verde scuro per indicare che sono comandi validi, ad eccezione di @returns.
• Potrebbe essere necessario compilare il progetto (o riavviare Xcode) prima che appaiano le ultime modifiche alla documentazione.

Dove vedere la documentazione:

1. Durante il completamento del codice, vedrai il breve testo:

Questo mostrerà il breve testo (senza formattazione); se non esiste un breve testo, mostrerà una concatenazione di tutto il testo fino al primo blocco @; se non ne esiste alcuna (ad es. si inizia con @return), si concederà tutto il testo rimuovendo tutti i comandi @.

2. Opzione-clic sul nome di un identificatore:

3. Nel pannello Ispettore Guida rapida

(Vedi il primo screenshot.)

4. In Doxygen

Poiché i comandi in Xcode 5 sono compatibili con Doxygen, è possibile scaricare e utilizzare Doxygen per generare file di documentazione.

Altre note

Per un'introduzione generale a Doxygen e come documentare il codice Objective-C, questa pagina sembra una buona risorsa.

Descrizioni di alcuni dei comandi supportati:

• @brief: inserirà il testo all'inizio del campo della descrizione ed è l'unico testo che verrà visualizzato durante il completamento del codice.

Quanto segue non funziona:

• \n: non genera una nuova riga. Un modo per creare una nuova riga è assicurarsi che nulla sia su quella linea. Neanche un singolo personaggio spaziale!
• \example

Non sono supportati i seguenti (non appaiono nemmeno in verde scuro):

• \citare
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• \ relatedalso
• \ rtfonly
• \ secreflist
• \corto
• \frammento
• \sommario
• \ vhdlflow
• \ ~
• \"
• .
• ::
• \ |

Parole chiave riservate da Apple:

Apple utilizza quelle che sembrano essere parole chiave riservate che funzionano solo nella loro documentazione. Anche se appaiono in verde scuro, sembra che non possiamo usarli come fa Apple. Puoi vedere esempi di utilizzo di Apple in file come AVCaptureOutput.h.

Ecco un elenco di alcune di queste parole chiave:

• @abstract, @availibility, @class, @discussion, @deprecated, @method, @property, @protocol, @related, @ref.

Nella migliore delle ipotesi, la parola chiave genererà una nuova riga nel campo Descrizione (ad es. @Discussion). Nel peggiore dei casi, la parola chiave e qualsiasi testo che segue non appariranno nella guida rapida (ad es. @Class).

Swift 2.0 utilizza la sintassi seguente:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Notate com'è @paramadesso - parameter.

Ora puoi anche includere i punti elenco nella tua documentazione:

/**
        - square(5) = 25
        - square(10) = 100
    */

Senseful:

Potrebbe essere necessario creare il progetto prima che appaiano le ultime modifiche alla documentazione.

A volte questo non è stato abbastanza per me. La chiusura di Xcode e l'apertura del backup del progetto di solito risolvono questi casi.

Inoltre sto ottenendo risultati diversi nei file .h e .m. Non riesco a ottenere nuove righe quando i commenti della documentazione si trovano in un file di intestazione.

La maggior parte della formattazione è cambiata per Swift 2.0 (a partire da Xcode7 ß3, vero anche in ß4)

anziché :param: thing description of thing (come in Swift 1.2)

è adesso - parameter thing: description of thing

La maggior parte delle parole chiave sono state sostituite - [keyword]: [description]invece di :[keyword]: [description]. Attualmente l'elenco di parole chiave che non funzionano include, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.