Usamos doxygen para generar documentación API (referencia) para nuestro código. Tenemos una pequeña API de Java y una gran API de C++. La herramienta habitual de elección para las API de Java es Javadoc, pero doxygen puede hacer ambas cosas y hemos decidido utilizar una única herramienta para ambas.
Con Javadoc, puede agregar una descripción general de cualquier paquete agregando un archivo con un nombre especial al código fuente. Luego, Javadoc muestra esta descripción general, con toda la documentación que desee incluir, junto con la documentación de las clases individuales. Los resúmenes de paquetes son útiles para explicar cómo se pretende que los grupos de clases relacionadas se usen juntos y pueden incluir diagramas, ejemplos y más. Debido a que son parte de la compilación de Javadoc, pueden vincularse a clases individuales (o métodos u otros miembros).
¿Cómo hago el equivalente en doxygen, tanto para los paquetes de Java como para los espacios de nombres de C++ (que usamos como paquetes )? Sé que puedo editar la página principal, que funciona como una descripción general de toda la API, pero quiero distribuir más la documentación. No quiero una página de resumen; Quiero una página de descripción general por partición de código lógico, y quiero que esa descripción general esté en el mismo directorio que el código (donde es más probable que se mantenga actualizado).
¿Hay alguna manera de hacer esto con doxygen, o tendré que escribir mis propias herramientas para agregar archivos a la salida de doxygen?
Resolvimos esto agregando archivos de descripción general en formato Markdown en el árbol de fuentes y haciendo un pequeño cambio de configuración.
En Doxyfile, configuramos GENERATE_TREEVIEW en sí . Esto habilita la tabla de contenido de la barra lateral, que es necesaria si desea que estos archivos de descripción general se muestren en alguna parte. (Normalmente, doxygen solo emite elementos de código: clases, interfaces, etc. La vista de árbol le brinda un lugar para colocar otras cosas). Mientras edita Doxyfile, asegúrese de que MARKDOWN_SUPPORT esté configurado en sí. (Creo que ese es el valor predeterminado).
Luego agregamos un archivo Markdown (extensión .md) a cada subdirectorio en nuestro árbol fuente. Doxygen es compatible con todas las características habituales de Markdown . Nombramos cada archivo para que coincida con su directorio contenedor. Por ejemplo, en el directorio "servidor" llamamos al archivo server.md.
La vista de árbol de doxygen habitual tiene secciones para espacios de nombres, clases, archivos y quizás otras cosas. (Esto puede variar según el idioma; el nuestro es C++). Nuestros archivos adicionales aparecen en una sección encima de estas secciones, lo cual tiene sentido: "clases" se trata solo de las clases, y la descripción general del paquete que explica cómo funcionan juntas se encuentra arriba eso. No intentamos una organización más elegante, ya que solo necesitábamos unos pocos archivos en ese nivel.