Javadoc: paquete.html o paquete-info.java

3 minutos de lectura

avatar de usuario
ellq

Al intentar crear comentarios Javadoc a nivel de paquete, ¿cuál es el método preferido? ¿A qué te dedicas?

paquete-info.java

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

paquete.html

  • ventajas
    • La 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.

  • package-info.java puede contener [package] anotaciones: no son necesariamente todos los documentos de la API.

    – Tom Hawtin – tachuela

    5 de septiembre de 2010 a las 2:12

  • No calificaría package-info.java como un 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 “información del paquete” no es un nombre de clase legal.

    – Scrubbie

    28 de diciembre de 2011 a las 18:45

  • 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 de javadoc, esto podría causar problemas en el caso de .html.

    – honeyp0t

    13 de julio de 2012 a las 12:06

  • En realidad, @Scrubbie, aunque debería tener razón, creo que puede especificar clases privadas de paquetes allí. 🙁 Sin embargo, estoy de acuerdo con tu opinión, usando package-info.java para Javadoc y Anotaciones no es un abuso de una clase.

    – mjaggard

    27 de septiembre de 2012 a las 10:22


  • @JonasN consulte stackoverflow.com/a/14708381/751579 (Sé que tuvo este problema hace 3 años, pero tal vez alguien más necesite la sugerencia ahora)

    – davidbak

    20 de noviembre de 2015 a las 22:45

avatar de usuario
dios de la basura

package-info.java: “Este archivo es nuevo en JDK 5.0 y es preferible a package.html”.—javadoc – El generador de documentación de la API de Java

Anexo: La gran diferencia parece ser anotaciones del paquete. Hay un poco más en el camino de la lógica en 7.4 Declaraciones de paquetes.

Anexo: También se menciona la función de anotación aquí y aquí.

Anexo: Ver también Qué package-info.java ¿por?.

  • ¿Alguna razón en particular por la que se prefiera?

    – El LQ

    5 de septiembre de 2010 a las 2:24

  • @TheLQ: supongo que las anotaciones del paquete, ya que el compilador tiene más información con la que trabajar; más arriba.

    – dios de la basura

    5 de septiembre de 2010 a las 2:49

  • Las anotaciones de paquetes son nuevas para mí y parecen una buena razón para usar package-info.java debido a su alcance.

    – apilador

    5 de septiembre de 2010 a las 2:55

  • 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 explica por qué debería importarme. Dicho esto, es un enlace bueno y útil.

    – Roboprog

    11 de julio de 2012 a las 21:29

  • usando package-info.java puede usar {@link} y otros doclets. Cuando vincula una clase java.lang, cuando se genera javadoc, obtiene automáticamente el {@link} que apunta 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 refactorización.

    – Luigi R. Viggiano

    23 mayo 2013 a las 17:13

¿Ha sido útil esta solución?

Esta web utiliza cookies propias y de terceros para su correcto funcionamiento y para fines analíticos y para mostrarte publicidad relacionada con sus preferencias en base a un perfil elaborado a partir de tus hábitos de navegación. Al hacer clic en el botón Aceptar, acepta el uso de estas tecnologías y el procesamiento de tus datos para estos propósitos. Configurar y más información
Privacidad