usar - Doxygen vs Javadoc
javadoc tags list (4)
Doxygen tiene una serie de características que JavaDoc no ofrece, por ejemplo, los diagramas de clases para las jerarquías y el contexto de cooperación, más páginas de resumen, navegación opcional con código fuente (reticulado con la documentación), soporte adicional de etiquetas 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.
Como Doxygen es compatible con las etiquetas JavaDoc estándar, puede ejecutar Doxygen en cualquier código fuente con comentarios JavaDoc en él. A menudo puede tener sentido ejecutar el código fuente sin JavaDoc, ya que los diagramas y la exploración del código fuente pueden ayudar a entender el código incluso sin la documentación. Y dado que la herramienta JavaDoc ignora las etiquetas desconocidas, incluso puede usar etiquetas adicionales de Doxygen sin romper la generación de JavaDoc.
Habiendo dicho todo esto, debo admitir que no he usado Doxygen durante mucho tiempo. En la actualidad, confío mucho en mi IDE para proporcionar la misma visualización y, por lo general, no leo JavaDoc como páginas HTML, sino que importo los archivos fuente a mi IDE para que pueda generar JavaDoc flyouts y puedo pasar 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á dispuesto a ejecutar herramientas que no sean de Java, entonces vale la pena probar Doxygen, ya que no requiere ningún cambio en su código de Java.
Me di cuenta de un artículo en MCCA 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 cualquiera de los enfoques? ¿Son mutuamente excluyentes? ¿Hay un plugin Maven para Doxygen?
Me gusta el hecho de que con Doxygen, puede obtener diagramas de clases que se muestran en la misma página que la documentación. Además, me gusta el hecho de que lo enlace directamente al código fuente, si es necesario. No obstante, no estoy al tanto si javadoc tiene estas características.
Solo usaría Doxygen con Java si es nuevo en Java y ha usado Doxygen anteriormente, reduciendo la curva de aprendizaje que experimentaría con javadoc. Si no ha utilizado Doxygen anteriormente, me quedaría 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 lenguajes compatibles) tanto como lo hace con Java, Doxygen es una buena opción, ya que podrá usarlo para ambos idiomas.
Ambas herramientas son fáciles de usar, con un conjunto de características similar. Ambos tienen complementos (o están predefinidos) para NetBeans y Eclipse, por lo que es aún más rápido generar documentos. Hay una gran cantidad de superposición en el estilo de comentario utilizado por cada uno, pero no son exactamente iguales, por lo que sería difícil mezclarlos juntos (tendría que conocer los detalles de ambos , dejando de lado las características que son específico para uno u otro). Nunca lo he usado, pero parece que hay un complemento Maven para Doxygen .
Una gran ventaja de JavaDocs es que simplemente funcionan. Todo lo que se necesita para compilarlo y visualizarlo está incluido en el JDK que ya debe tener instalado para compilar sus programas.
Por otro lado, Doxygen puede ser complicado de configurar y trabajar correctamente. pero si está configurado correctamente, debe poder generar archivos PDF, RTF y DocBooks, así como HTML. El HTML no está organizado de forma predeterminada como JavaDocs ya que index.html muestra una página en blanco de forma predeterminada. Además, las clases en línea y los miembros estáticos pueden necesitar indicadores especiales para ser incluidos en la documentación, y si desea generar un PDF, puede tener que lidiar con las molestias de su distribución de Linux que no tiene el comando pdflatex necesario (por ejemplo, Ubuntu / Mint ha tenido problemas recientemente) así que si usted solo puede 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. Una vez que supere los obstáculos, debería ser más flexible al tratar con proyectos que involucren algo más que Java.