Cómo configurar Doxygen para documentar correctamente las categorías de Objective-C

Question

Parece que Doxygen tiene un manejo idiosincrásico de las categorías de Objective-C y me gustaría saber si otros han podido solucionarlo con éxito. Me gustaría que doxygen documente todas las categorías en una clase como entidades separadas, independientemente de si la clase base está documentada o no.

Si agrego el marcado doxygen a una categoría en una clase base indocumentada - digamos NSString, entonces doxygen enumera la categoría y sus métodos en la lista de clase como una entidad separada.

/** 
* @category NSString(Foo) 
* @brief A sample category on NSString 
*/ 
@interface NSString(Foo) 
@end 

Resultados en una entidad documentada NSString (Foo) en la lista de la clase.

embargo, el ejemplo siguiente no se :

/** 
* @category CCFMyCustomClass(Foo) 
* @brief A category on a documented base class 
*/ 
@interface CCFMyCustomClass(Foo) 
@end 

En cambio, en este último caso, todos los métodos de CCFMyCustomClass (Foo) se incluyen en la documentación de CCFMyCustomClass - la clase base.

A continuación, aunque a menudo citada, no parecen ayudar con este problema:

• Doxygen and Objective-C categories

• http://www.duckrowing.com/2010/03/18/documenting-objective-c-with-doxygen-part-i/

Answer 1

Puede omitir Doxygen e ir con AppleDoc.

appledoc es una herramienta de línea de comandos que ayuda a los desarrolladores de Objective-C a generar documentación de código fuente similar a Apple a partir de comentarios de código fuente especialmente formateados. Está diseñado para tomar comentarios del código fuente legibles como sea posible para la entrada y usar los comentarios, así como el código fuente circundante para generar documentación visualmente atractiva en forma de HTML, así como conjunto de documentación de Xcode completamente indexado y navegable. Aunque hay varias herramientas que pueden crear documentación HTML para Objective-C, todas las que conozco me quedan cortas en cumplir con el mínimo de objetivos que se describen a continuación.

También está disponible en GitHub

Answer 2

Una solución, aunque no ideal es cree un grupo para los métodos de categoría, de modo que al menos estén agrupados en la página de documentación de la clase base.

Así que conforme al segundo ejemplo anterior:

/** @name CCCFMyCustomClass(Foo) 
      Methods defined only in CCFMyCustomClass(Foo) category */ 
//@{ 

/** 
* 
* @method someFooMethod 
* @brief Does some foo things 
* @details First foo, then more foo, etc. 
*/ 
- (void)someFoodMethod; 

//@} 

Aparte de eso, he encontrado ningún otro medio de separación de categorías en una clase base documentada.

Answer 3

me gustaría lanzar en otra votación para Appledoc. Es mucho más fácil obtener buenos resultados con Objective-C que con Doxygen.

Answer 4

documento mis clases (en los archivos de cabecera) como:

/** 
@interface MyAppDelegate 
@mainpage The iPhone App 

This is information about my app, and appears in the main HTML page.\n\n 

As with all iOS apps, the main entry point is an App Delegate @see MyAppDelegate 
@defgroup Classes Classes 
@{ 
@brief Miscellaneous Classes 

Classes that don't fit in any other category 
@{ 
*/ 
/** 
@brief The application's delegate 

A delegate object is instantiated by the main function, so this is effectively the main entry point for the app 
@see MyAppDelegate() 
*/ 
@interface MyAppDelegate : UIResponder <UIApplicationDelegate> 
... 
@end 

/** @} */ 

/** @} */ 

El.m archivo tiene una categoría de extensión donde tengo mis métodos de extensión privados. Esto se parece a:

/** 
@category MyAppDelegate(internal) 
@addtogroup Classes 
@{ 
*/ 

/** 
@brief Application delegate class extension 

Internal extension for the application delegate 
@see MyAppDelegate 
*/ 
@interface MyAppDelegate() 
... 
@end 

/** @} */ 

@implementation MyAppDelegate 
... 
etc 

consigo dos páginas html - para MyAppDelegate y MyAppDelegate() La primera incluye un ver-también para el segundo, aunque el ver-también en la segunda vuelta a la primera no funciona (Parece que hay un problema con la categoría @see(). Sin embargo, los métodos están divididos correctamente entre las dos páginas.

Creo que la clave es documentar solo sus métodos dentro de los bloques de interfaz @ Objective-C no dentro los bloques @implementation. También uso bloques @defgroup y @addtogroup para agrupar todos los módulos de un cierto tipo (como View Controllers, Models, etc.)

Espero que esto ayude a alguien