javadoc-snippet Example Usage

Setting up the Javadoc snippet

The javadoc-snippet plugin is based on the standard doxia snippet plugin. Snippets are defined in exactly the same way.

For example, the snippet used to generate the examples below is:

// START SNIPPET: sample
/**
 * Hello world!
 *
 * We can put HTML formatting in our comments. We might have
 * <ul>
 *     <li>A</li>
 *     <li>list</li>
 *     <li>of</li>
 *     <li>things</li>
 * </ul>
 *
 * or <code>some verbatim text</code>
 *
 * or perhaps even <b>italic</b> and <i>bold</i> formatting, spread over
 * <p>
 * a couple of paragraphs.
 *
 * But, most importantly, we can add our comments into our Maven site, giving them context and value.
 *
 */
// END SNIPPET: sample

Standard output from the snippet macro

Please refer to the Snippet Macro documentation for including snippets in your APT pages. The standard snippet macro looks something like:

 %{snippet|id=sample|file=...

Using this built-in doxia snippet macro, the output for our sample snippet is:

/**
 * Hello world!
 *
 * We can put HTML formatting in our comments. We might have
 * <ul>
 *     <li>A</li>
 *     <li>list</li>
 *     <li>of</li>
 *     <li>things</li>
 * </ul>
 *
 * or <code>some verbatim text</code>
 *
 * or perhaps even <b>italic</b> and <i>bold</i> formatting, spread over
 * <p>
 * a couple of paragraphs.
 *
 * But, most importantly, we can add our comments into our Maven site, giving them context and value.
 *
 */

Standard output using the javadoc-snippet plugin

To render the same snippet using the javadoc-snippet plugin, change the name of the macro to:

 %{javadoc-snippet|id=sample|file=...

Using the javadoc-snippet macro, the output for our sample snippet is now:

Hello world!

 We can put HTML formatting in our comments. We might have
 <ul>
     <li>A</li>
     <li>list</li>
     <li>of</li>
     <li>things</li>
 </ul>

 or <code>some verbatim text</code>

 or perhaps even <b>italic</b> and <i>bold</i> formatting, spread over
 <p>
 a couple of paragraphs.

 But, most importantly, we can add our comments into our Maven site, giving them context and value.

Formatted output using the javadoc-snippet plugin

To render the same snippet as non-verbatim text, and without the surrounding box, add the verbatim=false parameter to the macro declaration:

 %{javadoc-snippet|verbatim=false|id=sample|file=...

Using the javadoc-snippet macro with verbatim=false, the output for our sample snippet is now:

Hello world! We can put HTML formatting in our comments. We might have
  • A
  • list
  • of
  • things
or some verbatim text or perhaps even italic and bold formatting, spread over

a couple of paragraphs. But, most importantly, we can add our comments into our Maven site, giving them context and value.

This allows you to use HTML formatting in your javadoc comments, and have them render correctly in your maven site. All of the standard HTML elements used in Javadoc should be rendered correctly in your Maven Site page.