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, @b
y \b
ambos 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
@property
texto.) 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).