Multiple Line Code Example in Javadoc Comment

Multiple line code example in Javadoc comment

In addition to the already mentioned <pre> tags, you should also use the @code JavaDoc annotation, which will make life much easier when it comes to HTML entities issues (in particular with Generics), e.g.:

* <pre>
* {@code
* Set<String> s;
* System.out.println(s);
* }
* </pre>

Will give correct HTML output:

Set<String> s;
System.out.println(s);

While omitting the @code block (or using a <code> tag) will result in HTML like this:

Set s;
System.out.println(s);

For reference, a full list of tag descriptions available in Java SE 8 can be found here.

What is the correct way put multiple lines in a param tag for a Javadoc?

I'd say that the way you've done it is fine (Edit: Oh, maybe not. Looks like you need a good serving of <pre> if you want to maintain that particular formatting. Fortunately, the answer still works!).

Consider an expert-grade example from Apache Commons BooleanUtils...

/**
 * <p>Converts an Integer to a boolean specifying the conversion values.</p>
 * 
 * <pre>
 *   BooleanUtils.toBoolean(new Integer(0), new Integer(1), new Integer(0)) = false
 *   BooleanUtils.toBoolean(new Integer(1), new Integer(1), new Integer(0)) = true
 *   BooleanUtils.toBoolean(new Integer(2), new Integer(1), new Integer(2)) = false
 *   BooleanUtils.toBoolean(new Integer(2), new Integer(2), new Integer(0)) = true
 *   BooleanUtils.toBoolean(null, null, new Integer(0))                     = true
 * </pre>
 *
 * @param value  the Integer to convert
 * @param trueValue  the value to match for <code>true</code>,
 *  may be <code>null</code>
 * @param falseValue  the value to match for <code>false</code>,
 *  may be <code>null</code>
 * @return <code>true</code> or <code>false</code>
 * @throws IllegalArgumentException if no match
 */
public static boolean toBoolean(Integer value, Integer trueValue, Integer falseValue) {
    if (value == null) {
        if (trueValue == null) {
            return true;
        } else if (falseValue == null) {
            return false;
        }
    } else if (value.equals(trueValue)) {
        return true;
    } else if (value.equals(falseValue)) {
        return false;
    }
    // no match
    throw new IllegalArgumentException("The Integer did not match either specified value");
}

Just truncate your long lines and carry on until you need the next param (or you're otherwise done). Javadoc also supports a lot of HTML tags, such as <pre> for pre-formatted text. That's useful when your documentation is spacing-sensitive (including newlines).

/** and /* in Java Comments

The first form is called Javadoc. You use this when you're writing formal APIs for your code, which are generated by the javadoc tool. For an example, the Java 7 API page uses Javadoc and was generated by that tool.

Some common elements you'd see in Javadoc include:

@param: this is used to indicate what parameters are being passed to a method, and what value they're expected to have
@return: this is used to indicate what result the method is going to give back
@throws: this is used to indicate that a method throws an exception or error in case of certain input
@since: this is used to indicate the earliest Java version this class or function was available in

As an example, here's Javadoc for the compare method of Integer:

/**
 * Compares two {@code int} values numerically.
 * The value returned is identical to what would be returned by:
 * <pre>
 *    Integer.valueOf(x).compareTo(Integer.valueOf(y))
 * </pre>
 *
 * @param  x the first {@code int} to compare
 * @param  y the second {@code int} to compare
 * @return the value {@code 0} if {@code x == y};
 *         a value less than {@code 0} if {@code x < y}; and
 *         a value greater than {@code 0} if {@code x > y}
 * @since 1.7
 */
public static int compare(int x, int y) {
    return (x < y) ? -1 : ((x == y) ? 0 : 1);
}

The second form is a block (multi-line) comment. You use this if you want to have multiple lines in a comment.

I will say that you'd only want to use the latter form sparingly; that is, you don't want to overburden your code with block comments that don't describe what behaviors the method/complex function is supposed to have.

Since Javadoc is the more descriptive of the two, and you can generate actual documentation as a result of using it, using Javadoc would be more preferable to simple block comments.

Javadoc - multiline comment with annotation (@ sign)

OK, I've found answer elsewhere: https://stackoverflow.com/questions/2290757/how-can-you-escape-the-character-in-javadoc

the thing is to go for {@literal @}

So then:

/**
 * Whatever txt1 ...
 * <pre>
 * {@code
 *  {@literal @}Lob
 *  private byte[] foo;
 * }
 * </pre>
 * Whatever txt2 ...
 * 
 * @author $Author: $
 */
public class Foo {

renders correctly to:

Whatever txt1 ...

{@Lob
private byte[] foo;
}

Whatever txt2 ...
Author:
$Author: $

Should a java header be a javadoc or a multi-line comment?

If you (or someone) want to generate Javadoc (or keep the possibility for it) from the class, you'll want to use Javadoc comments. If you just want to be different for no reason (or really hate class javadoc), use a regular comment.

Of course if you're making a Javadoc comment, you should put something useful in it. Instead of name, date and description, you'll want to put some information about the class, how to use it etc. Not who made the class and when, that's irrelevant.

Intellij code formatting converting variable Javadoc from single line to multiline

Never Mind. Got this. There is an option in IntelliJ which says
"Do not wrap one line comments"

Sample Image

Breaking a long URL to several line in javadoc

If you don't want to use a URL shortener you can surround your url with <pre></pre> tags as follows:

/**
 * Class to do some cool stuff
 * Original source: 
 * <pre>
 * See <a href="http://stackoverflow.com/questions/
   and-huge-amouts-of-URL-address-which-does-not-fit-to-80-chars">NameOfyourLink</a>
 * </pre>
 */

This will satisfy checkstyle for example and let you keep your original URL.

IntelliJ: How to keep short one-line JavaDoc multiline?

do not wrap

JavaDoc: If the @param comment does not fit in one line

You can continue the description on new lines. For instance:

/*
 * . . .
 * @param p
 *            text describing the parameter can overflow the
 *            line. It doesn't even have to start on the line.
 *            Indenting is not necessary, but it's nice for
 *            readability. The asterisk at the start of each
 *            line does not appear in the docs. The description
 *            ends at the start of the next "@..." tag or the
 *            end of the comment block.
 */

Multiple Line Code Example in Javadoc Comment