CODEWITHSUNDEEP
javahtmljavadoc
Mark
Mark

Reputation: 17132

Multiple line code example in Javadoc comment

I have a small code example I want to include in the Javadoc comment for a method. 

/**
 * -- ex: looping through List of Map objects --
 * <code>
 * for (int i = 0; i < list.size(); i++) {
 *      Map map = (Map)list.get(i);
 *      System.out.println(map.get("wordID"));
 *      System.out.println(map.get("word"));
 * }
 * </code>
 * 
 * @param query - select statement
 * @return List of Map objects
 */

The problem is the code example shows up in the Javadoc with no line breaks making it hard to read. 

-- ex: looping through List of Map objects -- for (int i = 0; i list.size(); i++) { Map map = (Map)list.get(i); System.out.println(map.get("wordID")); System.out.println(map.get("word")); } 
Parameters
query - - select statement 
Returns:
List of Map objects

I guess I am wrong in assuming the code tag would handle line breaks. What is the best way to format code examples in Javadoc comments ?

Upvotes: 631

Views: 265164

Answers (19)

Nolequen
Nolequen

Reputation: 4245

Since Java 23 (JEP 467) you may use /// for Markdown comments:

/// ```
/// for (int i = 0; i < list.size(); i++) {
///      Map map = (Map)list.get(i);
///      System.out.println(map.get("wordID"));
///      System.out.println(map.get("word"));
/// }
/// ```

Upvotes: 0

Nolequen
Nolequen

Reputation: 4245

Since Java 18 (JEP 413) you may use @snippet tag:

/**
 * -- ex: looping through List of Map objects --
 * {@snippet :
 * for (int i = 0; i < list.size(); i++) {
 *      Map map = (Map)list.get(i);
 *      System.out.println(map.get("wordID"));
 *      System.out.println(map.get("word"));
 * }
 * }
 *
 * @param query - select statement
 * @return List of Map objects
 */

Upvotes: 22

Fabian Steeg
Fabian Steeg

Reputation: 45684

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.

Upvotes: 880

user1050755
user1050755

Reputation: 11691

A combination of two of the other solutions seems perfect:

* <pre>{@code
*     {@literal @}Override
*     public void someMethod() {
*         Set<String> s;
*     }
* }</pre>

ie. use <pre>{@code to start and }</pre> to end the snippet. Also, replace @ with {@literal @}.

Haven't found an easier solution. Quite sad for a language that has been under active development for decades.

Upvotes: 3

Manuel Jordan
Manuel Jordan

Reputation: 16271

I work through these two ways without any problem:

<pre>
<code>
 ... java code, even including annotations
</code>
</pre>

and

<pre class="code">
 ... java code, even including annotations
</pre>

Of course the latter is more simplest and observe the class="code" part

Upvotes: 1

Venryx
Venryx

Reputation: 17959

In Visual Studio Code at least, you can force a Javadoc comment to respect line-breaks by wrapping it in triple-backticks, as seen below:

/** ```markdown
 * This content is rendered in (partial) markdown.
 * 
 * For example, *italic* and **bold** text works, but [links](https://www.google.com) do not.
 * Bonus: it keeps single line-breaks, as seen between this line and the previous.
 ``` */

Upvotes: 0

MC Emperor
MC Emperor

Reputation: 22967

Here's my two cents.

As the other answers already state, you should use <pre> </pre> in conjuction with {@code }.

Use pre and {@code}

  • Wrapping your code inside <pre> and </pre> prevents your code from collapsing onto one line;
  • Wrapping your code inside {@code } prevents <, > and everything in between from disappearing. This is particularly useful when your code contains generics or lambda expressions.

Problems with annotations

Problems can arise when your code block contains an annotation. That is probably because when the @ sign appears at the beginning of the Javadoc line, it is considered a Javadoc tag like @param or @return. For example, this code could be parsed incorrectly:

/**
 * Example usage:
 *
 * <pre>{@code
 * @Override
 * public void someOverriddenMethod() {

Above code will disappear completely in my case.

To fix this, the line must not start with an @ sign:

/**
 * Example usage:
 *
 * <pre>{@code  @Override
 * public int someMethod() {
 *     return 13 + 37;
 * }
 * }</pre>
 */

Note that there are two spaces between @code and @Override, to keep things aligned with the next lines. In my case (using Apache Netbeans) it is rendered correctly.

Upvotes: 6

mljrg
mljrg

Reputation: 4620

I just read the Javadoc 1.5 reference here, and only the code with <and > must be enclosed inside {@code ...}. Here a simple example:

 /** 
 * Bla bla bla, for example:
 *
 * <pre>
 * void X() {
 *    List{@code <String>} a = ...;
 *    ...
 * }
 * </pre>
 *
 * @param ...
 * @return ...
 */
 .... your code then goes here ...

Upvotes: 4

Jin Kwon
Jin Kwon

Reputation: 21976

/**
 * <blockquote><pre>
 * {@code
 * public Foo(final Class<?> klass) {
 *     super();
 *     this.klass = klass;
 * }
 * }
 * </pre></blockquote>
 **/
  • <pre/> is required for preserving lines.
  • {@code must has its own line
  • <blockquote/> is just for indentation.
public Foo(final Class<?> klass) {
    super();
    this.klass = klass;
}

UPDATE with JDK8

The minimum requirements for proper codes are <pre/> and {@code}.

/**
 * test.
 *
 * <pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre>
 */

yields

 <T> void test(Class<? super T> type) {
     System.out.printf("hello, world\n");
 }

And an optional surrounding <blockquote/> inserts an indentation.

/**
 * test.
 *
 * <blockquote><pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre></blockquote>
 */

yields

     <T> void test(Class<? super T> type) {
         System.out.printf("hello, world\n");
     }

Inserting <p> or surrounding with <p> and </p> yields warnings.

Upvotes: 10

Christoph Naber
Christoph Naber

Reputation: 1921

I had a really tough time with including a specific code example in a javadoc comment. I'd like to share this one.
Please note the following:

  • usage of old <code> - tag to prevent the curly brackets from being interpreted
  • usage of "new" {@code ...} - tag to get the generics included in the output
  • escaping of the @ sign in @Override via "{@literal @}Override" because javadoc generator "tilts" there due to the fact that the @ goes directly after an opening curly bracket
  • remove one space in front of {@code and {@literal, to compensate inner spaces and keep the alignment

javadoc code: 

/** this methods adds a specific translator from one type to another type. `
  * i.e.
  * <pre>
  * <code>new BeanTranslator.Builder()
  *   .translate(
  *     new{@code Translator<String, Integer>}(String.class, Integer.class){
  *      {@literal @}Override
  *       public Integer translate(String instance) {
  *         return Integer.valueOf(instance);
  *       }})
  *   .build();
  * </code>
  * </pre>
  * @param translator
  */

gets printed as 

new BeanTranslator.Builder()
  .translate(
    new Translator<String, Integer>(String.class, Integer.class){
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();

Upvotes: 192

ifeegoo
ifeegoo

Reputation: 7292

If you are Android developer you can use:

<pre class=”prettyprint”>

TODO:your code.

</pre>

To pretty print your code in Javadoc with Java code.

Upvotes: 2

bitsdanceforme
bitsdanceforme

Reputation: 131

I was able to generate good looking HTML files with the following snip-it shown in Code 1.

 * <pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 *</pre>

(Code 1)

Code 1 turned into the generated javadoc HTML page in Fig 1, as expected.

A-->B
 \
  C-->D
   \   \
    G   E-->F

(Fig. 1)

However, in NetBeans 7.2, if you hit Alt+Shift+F (to reformat the current file), Code 1 turns in to Code 2.

 * <
 * pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 * </pre>

(Code 2)

where the first <pre> is now broken onto two lines. Code 2 produces generated javadoc HTML file as shown in Fig 2.

< pre> A-->B \ C-->D \ \ G E-->F

(Fig 2)

Steve B's suggestion (Code 3) seems to give the best results and remains formatted as expected even after hitting Alt+Shift+F.

*<p><blockquote><pre>         
* A-->B
*  \
*   C-->D
*    \   \
*     G   E-->F
* </pre></blockquote>

(Code 3)

Use of Code 3 produces the same javadoc HTML output as shown in Fig 1.

Upvotes: 5

Tamas
Tamas

Reputation: 776

There is a significant difference between <blockquote><pre>... and <pre>{@code.... The former will omit the type declarations in generics but the latter will keep it.

E.g.: List<MyClass> myObject = null; displays as List myObject = null; with the firts and as List<MyClass> myObject = null; with the second

Upvotes: 3

Eugene_CD-adapco
Eugene_CD-adapco

Reputation: 7

Using Java SE 1.6, it looks like all UPPERCASE PRE identifiers is the best way to do this in Javadoc:

/**
 * <PRE>
 * insert code as you would anywhere else
 * </PRE>
 */

is the simplest way to do this.

An Example from a javadoc I got from a java.awt.Event method:

/**
 * <PRE>
 *    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
 *    int offmask = CTRL_DOWN_MASK;
 *    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
 *        ...
 *    }
 * </PRE>
 */

This produces output that looks exactly like the regular code, with the regular code spacings and new lines intact.

Upvotes: -1

Jarek Przyg&#243;dzki
Jarek Przyg&#243;dzki

Reputation: 4402

I enclose my example code with <pre class="brush: java"></pre> tags and use SyntaxHighlighter for published javadocs. It doesn't hurt IDE and makes published code examples beautiful.

Upvotes: 0

Rule
Rule

Reputation: 630

You need the <pre></pre> tags for the line breaks, and the {@code ... } inside them for generics. But then it's not allowed to place the opening brace on the same line as the <generic> tag, because then everything will be displayed on 1 line again.

Displays on one line:

* ..
* <pre>
* {@code
* public List<Object> getObjects() {
*    return objects;
* }
* </pre>
* ..

Displays with line breaks:

* ..
* <pre>
* {@code
* public List<Object> getObjects() 
* {
*    return objects;
* }
* </pre>
* ..

Another weird thing is when you paste the closing brace of {@code, it gets displayed:

* ..
* <pre>
* {@code
*   public List<Object> getObjects() 
*   {
*     return objects;
*   }
* }
* </pre>
* ..

Output:

public List<Object> getObjects() 
{
   return objects;
}
}

Upvotes: 19

Steve B.
Steve B.

Reputation: 57274

The java source has lots of good examples for this. Here's an example from the head of "String.java":

....
 * is equivalent to:
 * <p><blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <p><blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
...

Upvotes: 43

Edwin
Edwin

Reputation: 2671

Try replacing "code" with "pre". The pre tag in HTML marks the text as preformatted and all linefeeds and spaces will appear exactly as you type them.

Upvotes: 1

Zach Scrivena
Zach Scrivena

Reputation: 29539

Enclose your multiline code with <pre></pre> tags.

Upvotes: 25

Related Questions