CODEWITHSUNDEEP
javanetbeanscommentsjavadoc
java.is.for.desktop
java.is.for.desktop

Reputation: 11216

Javadoc: line breaks without HTML-tags?

Sorry for a probable FAQ kind of question, but I just can't find the answer.

As far as I remember Eclipse, a blank line in a Javadoc comment is displayed (in in-source Javadoc popups) as a line break (with extra vertical spacing).

In Netbeans, however, this is not the case.

Can I configure Javadoc to interpret a blank line as a line break?

Additional question: Can I override default Netbeans behavior (related to this) for in-source Javadoc popups?

What I'm talking about is:

Source

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

Eclipse interpretation

 Paragraph One

 Paragraph Two

Netbeans interpretation

 Paragraph One Paragraph Two

Upvotes: 107

Views: 152887

Answers (7)

roylaurie
roylaurie

Reputation: 1858

I agree with you, HTML doesn't belong in source-code. Sadly, I didn't find much help Googling around for this. It's actually quite easy to implement.

Here's a custom Doclet that you can compile and use:

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);
    }
}

An example of how to invoke it using 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

Upvotes: 5

fujy
fujy

Reputation: 5264

There is already an option in NetBeans - tested on version 8.2 - that allows you to preserve new lines in your comments, and/or add a <p> tag to your Javadoc if needed

  • Just from the Tools menu, chose Options
  • Go to Editor tab, then Formatting tab
  • In the Language menu chose Java, and in Category menu chose Comments
  • Check the Preserve New Lines checkbox in the General section if you want to preserve new lines in your comments. This will preserve new lines without adding <p> tag
  • Check Generate "<p>" on Blank Lines checkbox in the Javadoc section if you also want to add <p> tag.

enter image description here

Upvotes: 16

user207421
user207421

Reputation: 310893

It has nothing to do with Netbeans. I suspect you are looking at the source code in one case and the output of Javadoc in the other case. Newlines are not significant in HTML: ergo the output will not show them. If you want a newline use a <p> or a <br>.

Upvotes: 105

AaA
AaA

Reputation: 3694

I'm not sure if this helps for OP's case, however I put <pre></pre> around my document so netbean does not mess up my formatting. So it will look like

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

This is closest I get to showing new lines in text format. I'm using NetBeans 7.1.2. This way using code format option will not reformat the document. Showing doc in hints is still formatted.

Update: in Netbeans 8.x there is an option in code formatting to disable formatting comments.

Upvotes: 52

Paŭlo Ebermann
Paŭlo Ebermann

Reputation: 74750

I have no idea what Eclipse is doing here, but if you want this behavior in general (not only an IDE), you may have to create a new Doclet (which may be based on the default HTML doclet) instead, there inserting a <p> at every empty line or such.

Upvotes: 0

java.is.for.desktop
java.is.for.desktop

Reputation: 11216

This is a pseudo-solution
(which sadly affects only generated javadoc, but does not affect Netbeans' in-source javadoc display).

Specify a stylesheet which contain the following:

div.block {
    white-space: pre;
}

Upvotes: 2

adarshr
adarshr

Reputation: 62583

JavaDoc displays the way the CSS styles have been defined. You could edit the CSS styles associated with paragraph tags to do this:

p {
    line-height: 25px;
}

Upvotes: 1

Related Questions