Doxygen vs Javadoc [cerrado]

Question

De un artículo en CACM me di cuenta de que Doxygen también funciona con Java (y varios otros idiomas). Pero Java ya tiene la herramienta Javadoc. ¿Alguien puede explicar cuáles son los pros y los contras de cada enfoque? ¿Son mutuamente excluyentes? ¿Hay un complemento de Maven para Doxygen?

Answer 1

Doxygen tiene una serie de características que JavaDoc no ofrece, por ejemplo, los diagramas de clase para las jerarquías y el contexto de cooperación, más páginas de resumen, navegación opcional de código fuente (con enlaces cruzados con la documentación), soporte de etiqueta adicional como @todo en una página separada y puede generar resultados en formato TeX y PDF También permite una gran cantidad de personalización visual.

Dado que Doxygen admite las etiquetas JavaDoc estándar, puede ejecutar Doxygen en cualquier código fuente con comentarios de JavaDoc. Con frecuencia, incluso puede tener sentido ejecutarse en código fuente sin JavaDoc, ya que los diagramas y la exploración del código fuente pueden ayudar a comprender el código incluso sin la documentación. Y como la herramienta JavaDoc ignora las etiquetas desconocidas, incluso puede usar etiquetas adicionales de Doxygen sin interrumpir la generación de JavaDoc.

Habiendo dicho todo esto, debo admitir que no he usado Doxygen durante mucho tiempo. Hoy en día tiendo a depender mucho de mi IDE para proporcionar la misma visualización y, por lo general, no leo JavaDoc como páginas HTML, sino que importo los archivos de origen a mi IDE para que pueda generar puntos flotantes de JavaDoc y puedo saltar a las definiciones. Eso es incluso más poderoso que lo que Doxygen tiene para ofrecer. Si desea tener documentación fuera del IDE y está feliz de ejecutar herramientas que no sean de Java, entonces vale la pena probar Doxygen, ya que no requiere ningún cambio en su código Java.

Answer 2

Solo usaría Doxygen con Java si eres nuevo en Java y has usado Doxygen antes, reduciendo la curva de aprendizaje que experimentarías con javadoc. Si no has usado Doxygen antes, me quedo con javadoc, ya que fue diseñado específicamente con Java en mente. Si no conoce ninguno de los dos y trabaja en C ++ (u otros idiomas compatibles) tanto como en Java, Doxygen es una buena opción, ya que podrá usarlo en ambos idiomas.

Ambas herramientas son fáciles de usar, con un conjunto de características similares. Ambos tienen complementos (o están pre-integrados) para NetBeans y Eclipse, lo que hace que la generación de documentos sea aún más rápida. Hay una gran cantidad de superposición en el estilo de comentario usado por cada uno, pero no son exactamente iguales, por lo que sería difícil mezclarlos (tendrías que saber los detalles de < em> both , omitiendo cualquier característica que sea específica de uno u otro). Nunca lo he usado, pero parece que hay un complemento de Maven para Doxygen .

Answer 3

Me gusta el hecho de que con Doxygen, puede obtener diagramas de clase en la misma página que la documentación. Además, me gusta el hecho de que lo vincula directamente con el código fuente, si es necesario. Sin embargo, no sé si javadoc tiene estas características.

Answer 4

Una gran ventaja de JavaDocs es que simplemente funcionan. Todo lo necesario para compilarlos y verlos está incluido en el JDK que ya necesita tener instalado para compilar sus programas.

Por otra parte, el Doxygen puede ser una molestia para configurar y trabajar correctamente. pero si se configura correctamente, debería poder generar archivos PDF, RTF y DocBooks, además de HTML. El HTML no está organizado tan bien como JavaDocs por defecto, ya que el index.html muestra una página en blanco por defecto. Además, las clases en línea y los miembros estáticos pueden necesitar indicadores especiales para incluirse en la documentación, y si desea generar un PDF, es posible que tenga que lidiar con las molestias de su distribución de Linux al no tener el comando pdflatex necesario (por ejemplo, Ubuntu / Mint ha tenido problemas recientemente) por lo tanto, si acaba de instalarlo y ejecutarlo, puede obtener una pantalla llena de errores incluso con un programa simple. En comparación con la facilidad de obtener javadoc automáticamente cuando instala la API, la configuración de Doxygen puede ser una experiencia miserable. Sin embargo, una vez que supere los obstáculos, debería ser más flexible al tratar con proyectos que involucran más que solo Java.