211
Al intentar crear comentarios de Javadoc a nivel de paquete, ¿cuál es el método preferido? ¿Qué haces?Javadoc: package.html o package-info.java
package-info.java
- Pros
- reciente
- Contras
- Abuso de una clase - Las clases son para el código, no sólo para los comentarios
package.html
- Pros
- extensión HTML significa que no es código
- resaltado de sintaxis en los editores de texto/IDE de
- Contras
- ¿Ninguna?
Para mí, siempre he utilizado Package.html. Pero me pregunto si es la elección correcta.
'package-info.java' puede contener anotaciones [paquete] - no es necesariamente todos los documentos API. –
No calificaría package-info.java como un abuso de una clase. Es un archivo fuente 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
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 enviar el javadoc como LaTeX o como un archivo PDF. Dependiendo de la implementación del compilador de javadoc, esto podría causar problemas en el caso .html. – honeyp0t