documentazione codice Xcode

Question

Esistono linee guida/standard su come documentare il codice scritto in XCode? Voglio dire, c'è un modo per documentare il codice se vuoi renderlo facilmente comprensibile agli altri? XCode fornisce uno strumento che può essere utilizzato per produrre automaticamente documentazione come i documenti di riferimento API dal tuo codice + commenti?

Almeno sono interessato a capire se esiste un modo standard di scrivere commenti prima di interfacce/protocolli/metodi definiti nel codice. Ho visto l'uso di direttive come il seguente, ma non ho capito come funzionano:

#pragma mark - 
#pragma mark Initialization 

Answer 1

è possibile unire queste due righe in una sola: #pragma mark - Initialization. Fai clic sulla lista dei metodi (in alto a destra) e vedrai un'intestazione in grassetto con una linea. È solo un marcatore per raggruppare i metodi in sezioni.

Il collegamento delle linee guida di codifica pubblicato da Derek sopra è una lettura obbligata.

Se si desidera produrre documentazione di tipo Apple, è necessario utilizzare questo strumento di terze parti eccellente e gratuito: http://www.gentlebytes.com/appledoc/ Apple non fornisce nulla di simile.

---

I tag sono una funzione ISO C per passare suggerimenti al compilatore.

L'unica aggiunta di pragma in XCode (AFAIK) è mark con - e/o testo. Questo crea una linea e/o un testo in grassetto nel metodo di ricerca.

// Mark a section in your code with a line and a bold text. 
// You can use the line or the text alone. 
#pragma mark - random text 

Se si sta modificando i file sulle lingue che non compilano con GCC, è ancora possibile utilizzare il marchio su commenti (questo funziona per le lingue GCC troppo):

// MARK: - random text 
/* MARK: more random text */ 

ma io uso #pragma Contrassegna perché il mio tema di colore ha la praga in rosso e risaltano meglio dei commenti. Se si desidera un frammento di codice pragma rilegato ad un tasto di scelta rapida, utilizzare

#pragma mark - <#Description#> 

in modo da poter scheda salto al testo descrizione.

più su pragma:

• What is a pragma?
• 6.56 Pragmas Accepted by GCC
• di Controlling Diagnostics via Pragmas
• Function attributes sono preferibili ai pragma, perché non è possibile generare pragma da macro e un pragma potrebbe avere un significato diverso in Clang un altro compilatore.

Answer 2

In aggiunta alla risposta di @ jano, utilizzare il formato seguente per descrivere la funzionalità del metodo.

/*! 
@function  getEmployeeDetails 
@abstract  getEmployeeDetails 
@discussion  This function will fetch employee details based on employee id 
@param   strEmpId 
employee unique id 
@result   an Array of Employee 
*/ 

-(NSArray*)getEmployeeDetails:(NSString *)strEmpId{ 
    /*Do somethings.*/ 
}