Generadores de documentación Objective-C: HeaderDoc vs. Doxygen vs. AppleDoc

documentation-generation (3)

Necesito implementar una solución de generación de documentación para mi lugar de trabajo y la he reducido a las tres mencionadas en el título. He podido encontrar muy poca información en el camino de las comparaciones formalizadas entre estas soluciones, y espero que aquellos de ustedes con experiencia en uno o más de los anteriores puedan tener en cuenta:

Esto es lo que pude obtener de mi pase inicial:

HeaderDoc Pros: coherente con los documentos existentes de Apple, compatibilidad con la creación de documentos de Apple
HeaderDoc Contras: comportamiento difícil de modificar, el proyecto no se trabaja activamente, muchos se han alejado (es decir, debe haber algo deficiente, aunque no puedo cuantificarlo).

Doxygen Pros: comunidad activa de soporte b / c de base amplia de uso, muy personalizable, la mayoría de los tipos de salida (como látex, etc.)
Doxygen Contras: toma trabajo para hacer que se vea / se comporte de manera consistente con los documentos de manzanas, la compatibilidad con los documentos de Apple no es tan simple

AppleDoc Pros: aspecto coherente con los documentos existentes de apple, compatibilidad con la creación de documentos de Apple,
AppleDoc Contras: Emite documentación sobre los tipos, entiendas y funciones, desarrollándose activamente

¿Esto suena exacto? Nuestra solución deseada tendrá:

Aspecto y tacto consistentes con manzanas referencia de clase c objetivo
Posibilidad de opción-clic para desplegar la referencia de documentación desde Xcode, y luego vincular al documento (al igual que las clases de Apple)
Manejo inteligente de categorías, extensiones y similares (incluso categorías personalizadas de las clases de Apple)
Posibilidad de crear nuestras propias páginas de referencia (como esta página: Cargando ... que pueden incluir imágenes, y ser enlazables a partir de referencias de clase generadas sin problemas, como la referencia de clase de UIViewController de Apple a la página enlazada.
Comandos de línea de comandos fáciles de ejecutar que pueden integrarse en scripts de compilación
Manejo elegante de una base de código muy grande

En base a toda la información anterior, ¿alguna de las soluciones anteriores es claramente mejor que las demás? Cualquier sugerencia o información para agregar sería extremadamente apreciada.

Como creador y desarrollador principal de doxygen, permítanme también proporcionar mi perspectiva
(obviamente también sesgado ;-)

Si está buscando una réplica 100% fiel del estilo de documentación propio de Apple, entonces AppleDoc es una mejor opción en ese sentido. Con Doxygen tendrás dificultades para obtener el mismo aspecto, así que no te recomendaría intentarlo.

Con respecto a los docsets de Xcode; Apple proporciona instructions cómo configurarlo con doxygen (escrito en el momento en que se lanzó Xcode 3). Para Xcode 4 también hay una buena guía sobre cómo integrar doxygen.

A partir de la versión 1.8.0, doxygen admite el marcado Markdown , así como una gran cantidad de comandos de markup adicionales.

Con doxygen puede incluir documentación en la página principal (@mainpage) y en las subpáginas (usando @subpage o @page). Dentro de una página puede crear secciones y subsecciones. De hecho, el manual del usuario de doxygen fue escrito completamente usando doxygen. Además de eso, puedes agrupar clases o funciones juntas (usando @defgroup y @ingroup) y dentro de una clase crear secciones personalizadas (usando @name).

Doxygen usa un archivo de configuración como entrada. Puede generar una plantilla con valores predeterminados usando doxygen -g o usar un editor gráfico para crear y editar uno. También puede canalizar opciones a través de doxygen a través de un script usando doxygen - (vea la pregunta 17 de las FAQ para ver un ejemplo)

Doxygen no se limita a Objective-C, es compatible con una amplia gama de idiomas, incluidos C, C ++ y Java. Doxygen tampoco se limita a la plataforma Mac, por ejemplo, también se ejecuta en Windows y Linux. La salida de Doxygen también admite más que solo HTML; puede generar resultados PDF (a través de LaTeX) o RTF y páginas man.

Doxygen también va más allá de la documentación pura; doxygen puede crear varios gráficos y diagramas a partir del código fuente (ver las opciones relacionadas con los dot ). Doxygen también puede crear una versión explorable y sintaxis resaltada de su código, y hacer una referencia cruzada con la documentación (consulte las opciones relacionadas con el navegador de origen ).

Doxygen es muy rápido para proyectos pequeños a medianos (la generación de diagramas puede ser lenta, pero hoy en día se ejecuta en múltiples núcleos de CPU en paralelo y los gráficos de una ejecución se vuelven a usar en la siguiente ejecución). Para proyectos muy grandes (por ejemplo, millones de líneas de código) doxygen permite que los proyectos se dividan en varias partes y luego puede vincular las partes como he explicado here .

Un buen ejemplo de la vida real del uso de doxygen para Objective-C se puede encontrar here .

El desarrollo de doxygen depende en gran medida de los comentarios de los usuarios. Tenemos una lista de correo activa para preguntas y discusiones, y un rastreador de errores para los errores y las solicitudes de funciones.

La mayoría de los usuarios de doxygen lo utilizan para códigos C y C ++, por lo que, naturalmente, estos lenguajes tienen el soporte más maduro y la salida está más ajustada a las características y necesidades de estos lenguajes. Dicho esto, también los deseos y problemas con otros idiomas se toman en serio.

Tenga en cuenta que hago casi todo el desarrollo de doxygen y la mayoría de las pruebas en una Mac.

Soy el autor de Appledoc, por lo que esta respuesta puede estar sesgada :) Aunque probé todos los generadores mencionados (y más), pero me frustré porque ninguno produjo los resultados que quería (objetivos similares a los tuyos).

Según sus puntos (solo menciono appledoc y doxygen, no recuerdo ese encabezado):

Aspecto consistente: Appledoc fuera de la caja, otra necesidad de modificar css, pero probablemente factible.
Generación de conjuntos de documentación (para referencias de Xcode): soporte completo de appledoc para la documentación que se puede buscar y hacer clic en la opción de forma inmediata, doxygen genera xml y makefile que necesita invocar usted mismo. Además appledoc admite docsets publicados fuera de la caja.
Categorías: appledoc le permite combinar categorías con clases conocidas o dejarlas separadas, las categorías de base y otras categorías de clase de apple se enumeran por separado en el archivo de índice . doxygen: esto no funcionaba mejor cuando lo probé.
Páginas de referencia personalizadas: appledoc supports el uso de marcación o html personalizado, doxygen: puede incluir documentación personalizada en la página principal, no sé si puede incluir más páginas.
Línea de comando fácil: depende de cómo lo mires: appledoc puede tomar todos los argumentos a través de los interruptores de línea de comando (pero también admite archivos plist de configuración de proyecto y globales opcionales) por lo que debe ser muy fácil de integrar con scripts de compilación. doxygen requiere el uso del archivo de configuración para configurar todos los parámetros.
Bases de código grandes: todas las herramientas deberían soportar esto, aunque no se compararon en el tiempo. Además, no estoy seguro de si alguna herramienta admite valores en caché (se ejecuta sobre los datos recopilados anteriormente para ahorrar tiempo). Estoy buscando agregar esto para la próxima versión principal.

¡Ya pasó un tiempo desde que traté de usar otras herramientas, por lo que los problemas antes mencionados con doxygen / headerdoc pueden haberse solucionado! appledoc también tiene desventajas: como mencionas, no hay soporte para enumeraciones, estructuras, funciones, etc. (se hizo un trabajo en esta dirección, revisa este fork ), y tiene su propio conjunto de problemas que pueden impedir tu uso, dependiendo tus requerimientos

Actualmente estoy trabajando en una actualización importante que cubrirá la mayoría de los problemas evidentes , incluido el soporte para enumeraciones, estructuras, etc. Regularmente estoy empujando cosas nuevas a la rama experimental tan pronto como termine los trozos más grandes y lo estabilice lo suficiente, para que pueda seguir el Progreso. Pero aún es muy temprano y el progreso depende de mi tiempo, por lo que puede llevar bastante tiempo hasta que funcione la solución.

Xcode 5 ahora analizará sus comentarios para buscar documentación y mostrarla:

Ya no tiene que usar Appledoc o Doxygen (al menos cuando no desea exportar sus documentos). Más información se puede encontrar here