La etiqueta que debe ser utilizado como separador de párrafo en Javadoc?

Que es el más apropiado etiqueta HTML para romper los párrafos/largas secciones de javadoc así que de acuerdo a las mejores prácticas?

Es <p /> o <br />? Por qué?

  • Depende de tu definición de «bonito», supongo. ¿Por qué no probar ambos y comprobar la diferencia en tu navegador?
  • Hmmm, supongo que por pantalla «bien» me refiero a «seguir las mejores prácticas».

3 Kommentare

  1. 56

    Bienvenido a la tierra de HTML 3.2.

    De acuerdo a la guía oficial sobre la escritura de comentarios de documentación, la forma correcta de separar los párrafos es con la etiqueta de párrafo: <P>. Echa un vistazo a la séptima viñeta en la sección sobre Formato de un documento de Comentarios.

    Normalmente, yo recomendaría fuertemente contra el uso de tales viejas, obsoletas prácticas para el marcado. Sin embargo, en este caso, hay una buena razón para hacer una excepción. La herramienta JavaDoc (a menos que la actualización radical con la costumbre de Doclets) genera edad, crufty, algo roto marcado. Los navegadores han sido diseñadas para ser compatible con el viejo loco de marcado del día, así que tiene sentido para que usted acaba de ir junto con él. El uso de <P> para separar los párrafos estará en línea con el resto de la JavaDoc de salida.

    • A pesar de que parece violar el código HTML de la semántica, parece bastante claro en la documentación que se encuentra.
    • No viole html semántica, no sólo se viola xhtml semántica.
  2. 30

    Estrictamente hablando un auto-cierre <p /> no tiene sentido, como <p> debe ser utilizado para contienen un párrafo, es decir, el párrafo debería estar encerrado por <p> y </p>.

    <br> sin embargo es un «nivel inferior» de la etiqueta que indica un salto de línea. Así que el semánticamente correcta para indicar los párrafos sería el uso de <p>:

    <p>This Foo is used to frobincate a {@link Baz}.</p>
    <p>It is quite groovy!</p>

    vs

    This Foo is used to frobincate a {@link Baz}.<br>
    It is quite groovy!

    Visualmente el <p> resultados en más espacios en blanco entre las líneas, mientras que un <br> se acaba de iniciar una nueva línea y no introducir cualquier espacio en blanco.

    • Por desgracia JDK8 forajidos de auto-cierre <br/>, ¿cuál es la alternativa?
    • podría usted dar por favor una referencia al lugar donde JDK8 forajidos de auto-cierre <br/>?
    • como usted sabe, los cambios de JavaDoc en JDK8 están muy lejos de alcanzar y estricto, pero no se muy bien documentado. Mi «prohibición» se refiere a mi observación de que el uso va a resultar en una acumulación de anular el fracaso, como siempre que no suprimirlo: [ERROR] ....java:24: error: self-closing element not allowed [ERROR] * instances.<br/>. Supongo que la solución es usar el HTML <br / > (al igual que yo estoy acostumbrado a usar <p> el párrafo separador en lugar de a nivel de bloque).
    • Yo no soy consciente de los cambios en el JavaDoc en JDK8, te agradecería si me apunte a un artículo o de la documentación o cualquier cosa que lo describe.
    • Si no son conscientes de ello, seguramente 🙂 – todo el internet que habla sobre ello. De todos modos, como he dicho, realmente no hay buena documentación sobre los cambios de Oracle hizo a la doclint herramienta en JDK8. La orden de trabajo es PEC 172: openjdk.java.net/jeps/172
    • Este es un gran consejo para HTML en general, pero en realidad es un mal consejo para Javadocs en particular. javadoc no juega bien con estos modernos mejores prácticas y las nuevas versiones son más estrictas acerca de la aceptación de marcado así.

  3. 6

    Con Java 8, un solo elemento inicial(<p>) obras.

    Nota que javadoc no como el elemento de cierre (</p>).

    • Pero, ¿por qué?! Yo lo he visto en el código y por eso estoy leyendo las respuestas a esta pregunta – que alguien de la izquierda <p> sin </p> y se ve bien a los demás, pero no para mí ://

Kommentieren Sie den Artikel

Bitte geben Sie Ihren Kommentar ein!
Bitte geben Sie hier Ihren Namen ein