Javadoc: ¿saltos de línea sin etiquetas HTML?

81

Perdón por una probable pregunta tipo FAQ, pero no puedo encontrar la respuesta.

Por lo que recuerdo Eclipse, se muestra una línea en blanco en un comentario de Javadoc (en las ventanas emergentes de Javadoc en la fuente) como un salto de línea (con espaciado vertical adicional).

En Netbeans, sin embargo, este no es el caso.

¿Puedo configurar Javadoc para interpretar una línea en blanco como un salto de línea?

Pregunta adicional: ¿Puedo anular el comportamiento predeterminado de Netbeans (relacionado con esto) para las ventanas emergentes de Javadoc en la fuente?

De lo que estoy hablando es:

Fuente

/**
 * Paragraph One
 *
 * Paragraph Two
 */
 void someMethod() { }

Interpretación del eclipse

 Paragraph One

 Paragraph Two

Interpretación de Netbeans

 Paragraph One Paragraph Two
java netbeans comments javadoc java.is.for.desktop
fuente
1
Muchas de estas respuestas ahora están desactualizadas (reemplazadas) por NetBeans8.2, vea la respuesta de @fujy a continuación, funciona perfectamente.
Webel IT Australia - votante positivo

Respuestas:

80

No tiene nada que ver con Netbeans. Sospecho que está mirando el código fuente en un caso y la salida de Javadoc en el otro caso. Las nuevas líneas no son significativas en HTML: ergo, la salida no las mostrará. Si desea una nueva línea, use a <p>o a <br>.

user207421
fuente
4
Como ya he mencionado en la pregunta, Eclipse tiene en cuenta las líneas en blanco como párrafos. Entonces mi suposición es que tiene que ser posible lograr esto mediante alguna configuración de javadoc (Netbeans o sin).
java.is.for.desktop
Eclipse le muestra el código fuente sin importar su formato. Netbeans 6.9.1 también le muestra el código fuente, ídem, es decir, tampoco ignora los saltos de línea. Sin embargo, si está mirando la salida de Javadoc por cualquier medio, sería incorrecto porque eso significa no ignorar los saltos de línea.
user207421
40

No estoy seguro de si esto ayuda en el caso de OP, sin embargo, puse <pre></pre>mi documento para que netbean no estropee mi formato. Entonces se verá como

/**
 * <pre>
 * Paragraph One
 *
 * Paragraph Two
 * </pre>
 */

Esto es lo más cerca que tengo de mostrar nuevas líneas en formato de texto. Estoy usando NetBeans 7.1.2. De esta manera, el uso de la code formatopción no volverá a formatear el documento. La visualización de documentos en sugerencias todavía tiene formato.

Actualización: en Netbeans 8.x hay una opción en el formato de código para deshabilitar los comentarios de formato.

AaA
fuente
13

Ya existe una opción NetBeans, probada en la versión 8.2, que le permite conservar nuevas líneas en sus comentarios y / o agregar una <p>etiqueta a su Javadocsi es necesario

  • Solo del Toolsmenú, elijaOptions
  • Vaya a la Editorpestaña, luegoFormatting pestaña
  • En el Languagemenú eligió Java, y en el Categorymenú eligióComments
  • Marque la Preserve New Linescasilla de verificación en la Generalsección si desea conservar nuevas líneas en sus comentarios. Esto preservará nuevas líneas sin agregar<p> etiquetas.
  • Marque la Generate "<p>" on Blank Linescasilla de verificación en la Javadocsección si también desea agregar una <p>etiqueta .

ingrese la descripción de la imagen aquí

fujy
fuente
2
Definitivamente la mejor respuesta wrt NetBeans 8.2. Fácil. Pero debe editarlo para agregar que solo se activa cuando realiza Formateo en el código (con saltos de línea existentes). Hay que tener cuidado, si ya hay algunos <p>a mano, a veces puede sumar el doble <p>``<p>la primera vez. A partir de entonces, funciona como se esperaba.
Webel IT Australia - votante positivo
4

Estoy de acuerdo contigo, HTML no pertenece al código fuente. Lamentablemente, no encontré mucha ayuda buscando en Google para esto. De hecho, es bastante fácil de implementar.

Aquí está el Doclet personalizado que puede compilar y usar:

import com.sun.javadoc.*;
import com.sun.tools.doclets.standard.*;

/**
 * Formats text-only comments with HTML.
 */
@SuppressWarnings("restriction")
public final class TextDoclet {
    private static final Pattern NEWLINE_REGEX = Pattern.compile("\\n");
    private static final String BR = "<br/>\n";

    public static boolean start(RootDoc rootDoc) {
        for ( ClassDoc classdoc : rootDoc.classes())
            classdoc.setRawCommentText(formatText(classdoc.getRawCommentText()));

        return Standard.start(rootDoc);     
    }

    private static String formatText(String text) {
        return NEWLINE_REGEX.matcher(text).replaceAll(BR);
    }
}

Un ejemplo de cómo invocarlo usando javadoc:

javadoc -docletpath ~/project/text-doclet/target/text-doclet-1.0.0-SNAPSHOT.jar -doclet com.myorg.textdoclet.TextDoclet -sourcepath ~/project/myapp/src/main/java -subpackages com.myorg.myapp
Roylaurie
fuente
2

JavaDoc muestra la forma en que se han definido los estilos CSS. Puede editar los estilos CSS asociados con las etiquetas de párrafo para hacer esto:

p {
    line-height: 25px;
}
Adarshr
fuente
1
Gracias, pero estoy seguro de que Netbeans no interpreta una línea en blanco como un párrafo (consulte "Interpretación de Netbeans" en mi pregunta). Quiero decir: solo puede definir el interlineado si tiene líneas.
java.is.for.desktop
Hmm. Vi eso. Pero no estoy realmente seguro de si Netbeans ofrece una opción para editar esto.
adarshr
2

Esta es una pseudo-solución
(que lamentablemente afecta solo al javadoc generado, pero no afecta la visualización del javadoc en el código fuente de Netbeans).

Especifique una hoja de estilo que contenga lo siguiente:

div.block {
    white-space: pre;
}
java.is.for.desktop
fuente
0

No tengo idea de lo que está haciendo Eclipse aquí, pero si desea este comportamiento en general (no solo un IDE), es posible que deba crear un nuevo Doclet (que puede estar basado en el doclet HTML predeterminado) en su lugar, insertando un <p>at cada línea vacía o tal.

Paŭlo Ebermann
fuente