¿Hay alguna manera de validar la presencia de Javadoc y / o comentarios de código en línea?

Estamos tratando de implementar processs de código de calidad para un gran proyecto en el que estoy trabajando. En este momento, muchos desarrolladores no están incorporando comentarios de código Javadoc o en línea en su código. Ok ahora mismo. Pero nos lastimará severamente en un futuro muy cercano. Estamos utilizando Maven 2.0.9 como nuestra herramienta de compilation, así como Hudson para la continuous integration. Estamos utilizando Subversion como nuestro repository de código / herramienta de creación de versiones fuente, Rational Application Developer y Rational Softare Architect (esencialmente Eclipse) 7.5.1 como nuestro IDE, y luego Subclipse como nuestro complemento Eclipse para conectarnos a SVN.

¿Hay un complemento o una forma de validar que un desarrollador ponga en Javadoc y / o comentarios de código en línea para permitir una confirmación a SVN? Esto no pretende ser un sustituto de buenas revisiones de código, sino simplemente una ayuda para asegurarse de que los desarrolladores agreguen esta documentation antes de comprometerse. Todavía tenemos la intención de realizar revisiones de códigos que también revisen la documentation.

¿Alguien ha encontrado algún complemento para algo como esto? Cualquier enlace? ¿Algunas ideas?

Necesita una herramienta que pueda escanear el text fuente y determinar si los javadocs están en su lugar. Idealmente, tal herramienta verificaría que los javadocs que desea estén en su lugar, que mencionen la configuration actual del software (nada peor que un comentario de Javadoc sobre un parámetro inexistente).

Idealmente, tal herramienta insertía el esqueleto de javadocs perdidos junto con el text que indica que no se rellenó correctamente.

Una herramienta ideal para hacer esto es un motor de transformación de progtwig, que puede leer el código fuente, ubicar los comentarios (o su ausencia), verificar la exactitud de los comentarios en la medida en que puedan determinarse a partir del código (types debidamente documentados, etc. ) e inserte los esqueletos según sea necesario.

Esto se puede lograr utilizando el kit de herramientas de reingeniería de software DMS , que tiene un analizador de Java con todas las funciones, crea AST [con comentarios retenidos] y tablas de símbolos. Necesitaría un código personalizado para caminar sobre los treees y hacer la inserción de verificación / comentario, pero esto debería ser bastante sencillo.

Definitivamente echa un vistazo al complemento Checkstyle Eclipse. Admite muchas comprobaciones de estilo, que se pueden configurar y creo que escuché sobre el complemento de Hudson. También verifica entre otros la presencia de comentarios.

Recientemente comencé una utilidad de comprobación JavaDoc de código abierto: OpenJavaDocCheck . El proyecto es bastante joven, pero algunas características son:

  • Salida XHTML + RDFa (o solo XML, para que pueda usar XSLT para crear lo que sea)
  • extensible (para probar patrones de JavaDoc específicos del proyecto, como tags personalizadas)

No estoy seguro si puede conectarlo fácilmente a un filter de enlace svn precommit, pero la integración en Maven podría hacerse con una llamada Ant como esta (tomada de este script de compilation demo.xml ):

<target name="demo"> <antcall target="ojdcheck-project"> <param name="project" value="com.github.ojdcheck"/> <param name="path" value="com.github.ojdcheck/src"/> </antcall> </target> <target name="ojdcheck-project"> <javadoc private="false" public="true"> <doclet name="com.github.ojdcheck.OpenJavaDocCheck" path="ojdcheck.jar:ojdcheck-jazzy.jar"> <param name="-xhtml"/> <param name="-file" value="../ojdcheck-ghpages/${project}.html"/> <param name="-tests" value="com.github.ojdcheck.jazzy.SpellCheckerTest"/> </doclet> <sourcepath> <pathelement path="${path}"/> </sourcepath> </javadoc> </target> 

La split en dos objectives no es necesaria, por supuesto, pero me facilita la ejecución de OpenJavaDocCheck en múltiples proyectos.

¿Tal vez doxygen tiene más posibilidades de configuration que javadoc? Debería ser compatible con los comentarios existentes de javadoc, por lo que podría valer la pena ejecutarlo en su código base.

Es posible hacer que falle un build de doxygen si hay cosas no documentadas en el código. Sin embargo, doxygen es tan lento que es cuestionable si es bueno tenerlo como un svn checkin hook.