Javadoc: package.html o package-info.java

230

Al intentar crear comentarios Javadoc a nivel de paquete, ¿cuál es el método preferido? ¿Qué haces?

package-info.java

  • Pros
    • Más nuevo
  • Contras
    • Abuso de una clase: las clases son para código, no solo para comentarios

package.html

  • Pros
    • Extensión HTML significa que no es código
    • Resaltado de sintaxis en IDE / editores de texto
  • Contras
    • ¿Ninguna?

Para mí, siempre he usado Package.html. Pero me pregunto si es la elección correcta.

java javadoc TheLQ
fuente
46
package-info.javapuede contener anotaciones [paquete]: no es necesariamente todos los documentos API.
Tom Hawtin - tackline
52
No calificaría package-info.java como abuso de una clase. Es un archivo fuente de Java (tiene una extensión de archivo ".java") pero no es un archivo de clase porque no contiene una declaración de clase. Y, de hecho, no puede contener una declaración de clase porque "package-info" no es un nombre de clase legal.
Scrubbie
19
Otra razón para usar package-info.java en lugar de package.html podría ser que .java no implica un formato de salida específico de la documentación. Por ejemplo, es posible que desee generar el javadoc como LaTeX o como un archivo PDF. Dependiendo de la implementación del compilador javadoc, esto podría causar problemas en el caso .html.
honeyp0t
3
En realidad @Scrubbie, aunque deberías tener razón, creo que puedes especificar clases de paquetes privados allí. :-( Estoy de acuerdo con su sentimiento, sin embargo, el uso package-info.javade Javadoc y anotaciones no constituye un abuso de una clase.
mjaggard
2
@JonasN vea stackoverflow.com/a/14708381/751579 (Sé que tuvo este problema hace 3 años, pero tal vez alguien más necesita la propina ahora)
davidbak

Respuestas:

269

package-info.java: "Este archivo es nuevo en JDK 5.0, y es preferible a package.html". - javadoc - El generador de documentación de API de Java

Anexo: La gran diferencia parece ser las anotaciones de paquete . Hay un poco más de justificación en 7.4 Declaraciones de paquetes .

Anexo: La función de anotación también se menciona aquí y aquí .

Anexo: Ver también ¿package-info.java Para qué ? .

trashgod
fuente
3
¿Alguna razón particular por la que se prefiere?
TheLQ
2
@TheLQ: supongo que las anotaciones del paquete, ya que el compilador tiene más información para trabajar; Más arriba.
trashgod
3
Las anotaciones de paquetes son nuevas para mí, y parecen una buena razón para package-info.java debido a su alcance.
apilador
66
Edite la respuesta un poco más: explique la "anotación del paquete", una anotación que se aplicará a todas las clases en un paquete o de lo contrario a los paquetes en su conjunto. El enlace tech.puredanger.com fue el único que realmente explicó por qué debería importarme. Dicho esto, es un enlace bueno y útil.
Roboprog
55
usando package-info.java puedes usar {@link} y otros doclets. Cuando vincula una clase java.lang, cuando se genera javadoc automáticamente obtiene {@link} apuntando al javadoc en línea de la clase que coincide con el jdk que está utilizando; ide también puede ayudar a detectar enlaces incorrectos cuando refactoriza la refactorización.
Luigi R. Viggiano