Estoy usando Check-Style, FindBugs y PMD para validar mi código de Java. He solucionado casi todos los errores capturados por estas herramientas.¿Cómo agregar comentarios a nivel de paquete en Javadoc?
No puedo entender cómo escribir "package comment", que es un error atrapado por checkstyle. He revisado la documentación de Check-Style, pero no lo entiendo.
¿Podría alguien ayudarme a escribir un comentario de nivel de paquete en Java?
Tiene que hacer una página package.html ubicada dentro del paquete. Puede leer sobre el contenido y la estructura de este archivo en el How to Write Doc Comments for the Javadoc Tool page.
Al usar un archivo .html para sus comentarios. Por favor, consulte este documento: How to Write Doc Comments for the Javadoc Tool.
package-info.java en su paquete de documentarLa siguiente enlace proporciona más información: http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html
Se recomienda paquete -info.java, si está presente, tomar el lugar de package.html para javadoc y otros sistemas de generación de documentación similares
paquete anotaciones de ancho también se declararon en package-info.java
Greetz, ghad
Nunca antes había oído hablar de este método. ¿Puede proporcionar un enlace a un documento que lo describa? –
@Thomas Owens http://java.sun.com/docs/books/jls/third_edition/html/packages.html – emory
Forma el enlace: se recomienda que package-info.java, si está presente, tome el lugar de package.html para javadoc y otros sistemas de generación de documentación similares. – GHad
Google considera esta como el primer éxito:
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#packagecomments
Usted acaba de crear un archivo llamado package.html en cada paquete.
Los comentarios javadoc a nivel de paquete se colocan en un archivo llamado package-info.java dentro del directorio del paquete. Que contiene el comentario y una declaración del paquete:
/**
* Provides the classes necessary to create an applet and the classes an applet uses
* to communicate with its applet context.
* <p>
* The applet framework involves two entities:
* the applet and the applet context. An applet is an embeddable window (see the
* {@link java.awt.Panel} class) with a few extra methods that the applet context
* can use to initialize, start, and stop the applet.
*
* @since 1.0
* @see java.awt
*/
package java.lang.applet;
Esto está documentado aquí: Package Comment Files
Interesante. La página sobre cómo escribir comentarios para Javadoc (ver mi respuesta) ni siquiera menciona esto. –
@Thomas: mantener la superposición de la documentación consistentemente actualizada es una perra. –
De hecho lo es. Hubiera sospechado que Sun (y ahora Oracle) habría hecho un mejor trabajo al mantener la documentación. Especialmente porque he estado haciendo el desarrollo de Java durante más de 5 años y nunca antes había visto ni escuchado sobre este método de producción de documentación a nivel de paquete. –
Puede añadir documentación a nivel de paquete.
Normalmente package-info.java contiene sólo una declaración del paquete, inmediatamente precedida por las anotaciones en el paquete. Si bien el archivo podría contener técnicamente el código fuente de una o más clases privadas del paquete, sería muy malo.
Se recomienda que package-info.java, si está presente, tome el lugar de package.html para javadoc y otros sistemas similares de generación de documentación.Si este archivo está presente, la herramienta de generación de documentación debe buscar el comentario de la documentación del paquete inmediatamente anterior a la declaración del paquete (posiblemente anotada) en package-info.java. De esta forma, package-info.java se convierte en el único repositorio de anotaciones y documentación a nivel de paquete. Si, en el futuro, resulta conveniente agregar cualquier otra información a nivel de paquete, este archivo debería ser un hogar conveniente para esta información.
Hay dos formas de añadir documentación de nivel de paquete utilizando javadoc:
Más detalles y ejemplos son here. Cuál usar: Javadoc: package.html or package-info.java
¿Por qué votar abajo? –
Supongo que esto se debe a que no se menciona package-info.java en absoluto (que es la variante preferida hoy en día). –