¿Cómo documento paquetes en Java?

182

En las API de Java puedo ver los comentarios de Javadoc para los paquetes.

¿Cómo / dónde coloco los comentarios Javadoc para documentar un paquete?

java packages javadoc jjnguy
fuente

Respuestas:

257

A partir de 1.5, puede definir un package-info.javaarchivo y proporcionar un comentario de estilo javadoc estándar para un paquete:

com / foo / package-info.java:

/**
 * com.foo is a group of bar utils for operating on foo things.
 */
package com.foo;

//rest of the file is empty

Especificación de idioma para paquetes

Gareth Davis
fuente
3
Enlace directo a la especificación: docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1
gavenkoa
77
en intellij puede hacer clic derecho en un paquete y la opción para crearlo debería estar en el nuevo menú de archivo
bsautner
Encontré que el archivo debía estar en packagename / src / packagename (con el resto de los archivos de origen)
trindflo
48

Hasta Java 1.4 incluido, tenía que proporcionar un archivo HTML package.html, como se describe en las otras respuestas.

Desde Java 1.5 también puede proporcionar un package-info.java, que contiene un comentario regular de Javadoc (sin HTML). Se prefiere este último, ya que le brinda algunas características adicionales (especialmente las anotaciones del paquete).

Detalles: documentos de Sun para javadoc

sleske
fuente
2
+1 por mencionar ambas formas y la diferencia esencial entre ellas. Por cierto, al menos IntelliJ IDEA actualmente tiene un mejor soporte para package.html (Ctrl-Q en el nombre de un paquete muestra el paquete Javadocs).
Jonik
3
Actualización de mi comentario anterior: hoy en día IDEA es compatible package-info.java.
Jonik
4

Con un package.htmlarchivo a nivel de paquete (es decir, en el directorio de ese paquete). Este debe ser un HTMLarchivo completamente formado , con la <html>etiqueta definida en él

oxbow_lakes
fuente
1
¿Más detalles? ¿Cómo debería ser el archivo?
jjnguy
1
Es un archivo HTML que contiene la descripción de su paquete. ¡Eso es!
oxbow_lakes
3
Esta es la vieja forma de hacerlo. Desde Java 1.5 en adelante, puede usar
package-info.java