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


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 de soporte activo b / c de base de amplio uso, muy personalizable, la mayoría de los tipos de salida (como látex, etc.)
Doxygen Contras: Toma trabajo para que se vea / se comporte de manera consistente con los documentos de Apple, la compatibilidad con los documentos de Apple no es tan simple

AppleDoc Pros: Se ve coherente con los documentos existentes de Apple, la compatibilidad con la fabricación de documentos de Apple,
AppleDoc Contras: Problema con documentación de typedefs, enums 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.


74
2018-04-11 15:52


origen


Respuestas:


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 instrucciones cómo configurarlo con doxygen (escrito en el momento en que se lanzó Xcode 3). Para Xcode 4 también hay un buena guía cómo integrar doxygen

A partir de la versión 1.8.0, doxygen admite Marcado de Markdown, así como una gran cantidad de margen comandos.

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 de usuario de doxygen fue completamente escrito 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 usa 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 - (ver pregunta 17 del Preguntas más frecuentes para un ejemplo)

Doxygen no se limita a Objective-C, es compatible con una amplia gama de idiomas, incluidos C, C ++ y Java. Doxygen tampoco está limitado a la plataforma Mac, p. se ejecuta en Windows y Linux también. 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 punto opciones relacionadas). 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 (ver navegador fuente opciones relacionadas).

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 se pueden unir las partes como lo expliqué aquí.

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

El desarrollo de doxygen depende en gran medida de los comentarios de los usuarios. Tenemos un activo lista de correo para preguntas y discusiones y una localizador de bichos para ambos errores y solicitudes de características.

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.


89
2018-04-12 18:41



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):

  1. Aspecto consistente: Appledoc fuera de la caja, otra necesidad de modificar css, pero probablemente factible.

  2. 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 es compatible docsets publicados fuera de la caja.

  3. Categorías: appledoc te permite fusionar categorías a las clases conocidas o dejarlas separadas, las categorías de base y otras categorías de clase de manzana se enumeran por separado en archivo de índice. doxygen: esto no funcionaba mejor cuando lo probé.

  4. Páginas de referencia personalizadas: appledoc apoyos listo para usar usando markdown o html personalizado, doxygen: puede incluir documentación personalizada en la página principal, no sé si puede incluir más páginas.

  5. 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.

  6. 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 tenedor), y tiene su propio conjunto de problemas eso puede evitar que lo use, dependiendo de sus requisitos.

Actualmente estoy trabajando en una actualización importante que cubre la mayoría de los problemas flagrantes, incluyendo 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 haga lo suficientemente estable, 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.


82
2018-04-12 12:32



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

Comment example

Ya no tiene que usar Appledoc o Doxygen (al menos cuando no desea exportar sus documentos). Se puede encontrar más información aquí


12
2017-09-19 16:05