Documentación del código Xcode

Question

¿Existen directrices/normas sobre cómo documentar el código escrito en XCode? Quiero decir, ¿hay alguna manera de documentar el código si quieres que otros lo entiendan fácilmente? ¿XCode proporciona un instrumento que se puede usar para producir automáticamente documentación como los documentos de referencia API de su código + comentarios?

Al menos estoy interesado en comprender si hay una forma estándar de escribir comentarios antes de las interfaces/protocolos/métodos definidos en su código. He visto el uso de directivas como la siguiente, pero no entiendo cómo funcionan:

#pragma mark - 
#pragma mark Initialization 

Answer 1

puede combinar esas dos líneas en una: #pragma mark - Initialization. Haga clic en la lista de métodos (arriba, derecha) y verá un encabezado en negrita con una línea. Es solo un marcador para agrupar métodos en secciones.

El enlace de las Pautas de codificación publicado por Derek arriba es una lectura obligada.

Si desea producir documentación similar a Apple, debe utilizar esta excelente y gratuita herramienta de terceros: http://www.gentlebytes.com/appledoc/ Apple no le proporciona nada parecido.

---

Pragmas son una característica ISO C para pasar sugerencias al compilador.

La única adición de pragma en XCode (AFAIK) es mark con - y/o texto. Esto crea una línea y/o texto en negrita en el buscador de métodos.

// 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 

Si está editando archivos en idiomas que no compila con GCC, todavía se puede utilizar la marca en los comentarios (esto funciona para idiomas CCG también):

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

pero yo uso #pragma marca porque mi tema de color tiene pragmas en rojo y se destacan mejor que los comentarios. Si quieres un fragmento de código pragma binded a una tecla de acceso directo, utilice

#pragma mark - <#Description#> 

por lo que puede ficha salto al texto de la descripción.

Más sobre pragmas:

• What is a pragma?
• 6.56 Pragmas Accepted by GCC
• de Controlling Diagnostics via Pragmas
• Function attributes se prefieren a pragmas porque no se puede generar pragmas de macros y un pragma puede tener un significado diferente en Clang otro compilador

Answer 2

Agregando a la respuesta de @ jano, use el siguiente formato para describir la funcionalidad de su método.

/*! 
@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.*/ 
}