Una de las nuevas características de Xcode 5 es la capacidad de documentar su propio código con una sintaxis de comentario especial. El formato es similar al doxygen, pero parece admitir solo un subconjunto de esas características .

¿Qué comandos son compatibles y cuáles no?
¿Alguno de sus usos difiere del doxygen?

Aquí hay un ejemplo de todas las opciones que he encontrado a partir de Xcode 5.0.2

Eso se generó con este código:

/** 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 {}

Notas:

• Los comandos deben estar en una /** block */, /*! block */o como prefijo ///o //!.
• Los comandos funcionan con el prefijo@ ( estilo headerdoc ) o \( estilo doxygen ). (Es decir, @by \bambos hacen lo mismo).
• Los comandos generalmente vienen antes del elemento que están describiendo. (Es decir, si usted está tratando de documentar una propiedad, el comentario debe presentarse ante el @propertytexto.) Pueden venir después, en la misma línea, con /*!<, /**<, //!<, ///<.
• Puede agregar documentación a clases, funciones, propiedades y variables .
• Todos estos comandos aparecen en texto verde oscuro para indicar que son comandos válidos, excepto @returns.
• Es posible que deba crear su proyecto (o reiniciar Xcode) antes de que aparezcan los últimos cambios en su documentación.

Dónde ver la documentación:

1. Durante el código completo, verá el breve texto:

Esto mostrará el texto breve (sin formato); si no existe un texto breve, mostrará una concatenación de todo el texto hasta el primer @block; si no existe ninguno (por ejemplo, comienza con @return), entonces concatá todo el texto eliminando todos los comandos @.

2. Opción haciendo clic en el nombre de un identificador:

3. En el panel Inspector de ayuda rápida

(Ver primera captura de pantalla).

4. En Doxygen

Dado que los comandos en Xcode 5 son compatibles con Doxygen, puede descargar y usar Doxygen para generar archivos de documentación.

Otras notas

Para una introducción general a Doxygen y cómo documentar el código Objective-C, esta página parece un buen recurso.

Descripciones de algunos de los comandos admitidos:

• @brief: insertará texto al comienzo del campo de descripción y es el único texto que aparecerá durante la finalización del código.

Lo siguiente no funciona:

• \n: no genera una nueva línea. Una forma de crear una nueva línea es asegurándose de que no haya nada en esa línea. ¡Ni siquiera un solo personaje espacial!
• \example

Los siguientes no son compatibles (ni siquiera aparecen en verde oscuro):

• \citar
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• \ relación también
• \ rtfonly
• \ secreflist
• \corto
• \retazo
• \Tabla de contenido
• \ vhdlflow
• \ ~
• \ "
• .
• :: ::
• \ |

Palabras clave reservadas de Apple:

Apple usa lo que parecen ser palabras clave reservadas que solo funcionan en su documentación. Aunque aparecen en verde oscuro, parece que no podemos usarlos como lo hace Apple. Puede ver ejemplos del uso de Apple en archivos como AVCaptureOutput.h.

Aquí hay una lista de algunas de esas palabras clave:

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

En el mejor de los casos, la palabra clave causará una nueva línea en el campo Descripción (por ejemplo, @discussion). En el peor de los casos, la palabra clave y el texto que la sigue no aparecerán en la ayuda rápida (por ejemplo, @class).

Swift 2.0 usa la siguiente sintaxis:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Fíjate cómo @parames ahora - parameter.

Ahora también puede incluir viñetas en su documentación:

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

Senseful:

Es posible que deba crear su proyecto antes de que aparezcan los últimos cambios en su documentación.

A veces esto no ha sido suficiente para mí. Cerrar Xcode y abrir la copia de seguridad del proyecto generalmente soluciona esos casos.

También obtengo resultados diferentes en archivos .h y archivos .m. No puedo obtener nuevas líneas cuando los comentarios de la documentación están en un archivo de encabezado.

La mayor parte del formato ha cambiado para Swift 2.0 (a partir de Xcode7 ß3, también cierto en ß4)

en lugar de :param: thing description of thing (como lo fue en Swift 1.2)

Esto es ahora - parameter thing: description of thing

La mayoría de las palabras clave han sido reemplazadas por en - [keyword]: [description]lugar de :[keyword]: [description]. Actualmente la lista de palabras clave que no hacen el trabajo incluye, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.