objective c - objective - ¿Cuáles son los nuevos comandos de documentación disponibles en Xcode 5?

xcode reference

Question

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 a Doxygen, pero parece que solo admite un subconjunto de esas características .

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

Answer 1

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

Eso fue generado 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 un /** block */ , /*! block */ /*! block */ , o prefijado con /// o //! .
• Los comandos funcionan con el headerdoc @ (estilo del headerdoc ) o el prefijo / (estilo doxygen ). (Es decir, @b y /b ambos hacen lo mismo).
• Los comandos generalmente vienen antes del artículo que están describiendo. (Es decir, si está intentando documentar una propiedad, el comentario debe venir antes del texto @property ). Pueden aparecer 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, a excepción de @returns .
• Es posible que necesite construir 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, comienzas con @return), concaturalizará todas las secuencias de texto de todos los comandos @.

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

3. En el panel Inspector de ayuda rápida

(Ver la 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 compatibles:

• @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 asegurarse 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
• / relationdalso
• / rtfonly
• / secreflist
• /corto
• /retazo
• /Tabla de contenido
• / vhdlflow
• / ~
• / "
• .
• ::
• / |

Palabras reservadas de Apple:

Apple usa lo que parece 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 generará una nueva línea en el campo Descripción (por ejemplo, @discusión). 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).

Answer 2

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

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

ahora es - parameter thing: description of thing

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

Answer 3

Senseful:

Es posible que necesite construir 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 suele remediar esos casos.

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

Answer 4

Swift 2.0 usa la siguiente sintaxis:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Observe cómo @param es ahora - parameter .

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

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