Adding syntax highlighting to Javadocs

Often times, when writing Javadocs, it helps to include source code samples along with the documentation. Typically, this is achieved by inserting the source code into a <pre> tag. This will render the code in a monospaced font when viewed in a browser.

/**
 * <p>Represents a fruit.</p>
 * <pre>
 * //create a new fruit
 * Fruit fruit = new Fruit("banana");
 *
 * //copy an existing fruit
 * Fruit copy = new Fruit(fruit);
 * </pre>
 * @author John Doe
 */
public class Fruit{
  ...
}

But there tools out there that can add syntax highlighting to source code on a web page. Javadocs are a webpage. Why can't these syntax highlighting tools be applied to Javadocs as well?

In this blog post, I am going to show you how to add syntax highlighting to a Maven-enabled Java project. I will be using the popular Javascript-based SyntaxHighlighter library for the syntax highlighting.

1. Download SyntaxHighligher

First, download SyntaxHighlighter.

2. Create a CSS file

SyntaxHighlighter makes use of CSS styling to perform the code coloring. Luckily, the Javadoc tool allows you to specify a CSS file to customize the look and feel of your Javadoc webpage. So, we will need to create a CSS file that contains the styling that SyntaxHighlighter requires.

Navigate to the SyntaxHighlighter files that you downloaded in the previous step. In the "styles" directory, locate the "shCore.css" file and one of the "shTheme" files (such as "shThemeDefault.css", see: all the available themes). Combine these two files into a single file and give it a name of your choosing. Save this file somewhere within your project folder. The location doesn't matter, since Javadoc will end up copying the file when the Javadocs are generated. A good place is the "src/main/javadoc" folder, as this is the standard Maven location for all Javadoc-related resources.

3. Configure your POM file

Next, we will need to add some configuration settings to the project POM. In the configuration section of the "maven-javadoc-plugin" plugin, add the following: (1) the location of the CSS file that was created in the previous step, (2) <script> tags for the SyntaxHighlighter Javascript files, and (3) Javascript code to configure and initialize SyntaxHighlighter.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.8.1</version>
  <configuration>

    <!-- (1) CSS file location -->
    <stylesheetfile>src/main/javadoc/syntax-highlighter.css</stylesheetfile>

    <!-- (2) SyntaxHighlighter Javascript files -->
    <top><![CDATA[
      <script src="http://alexgorbatchev.com/pub/sh/current/scripts/shCore.js" type="text/javascript"></script>
      <script src="http://alexgorbatchev.com/pub/sh/current/scripts/shBrushJava.js" type="text/javascript"></script>
    ]]></top>

    <!--
    (3) SyntaxHighlighter configuration and initialization
    See: http://alexgorbatchev.com/SyntaxHighlighter/manual/configuration/
    -->
    <footer><![CDATA[
      <script type="text/javascript">
        SyntaxHighlighter.defaults["auto-links"] = false;
        SyntaxHighlighter.defaults["tab-size"] = 2;
        SyntaxHighlighter.all();
      </script>
    ]]></footer>

  </configuration>
</plugin>

A list of available SyntaxHighlighter configuration settings can be found on the SyntaxHighlighter homepage.

4. Modify the Javadocs

Each <pre> tag in the Javadocs must be given a class="brush:java" attribute. This signals to SyntaxHighlighter that the text content should be treated as Java source code.

/**
 * <p>Represents a fruit.</p>
 * <pre class="brush:java">
 * //create a new fruit
 * Fruit fruit = new Fruit("banana");
 *
 * //copy an existing fruit
 * Fruit copy = new Fruit(fruit);
 * </pre>
 * @author John Doe
 */
public class Fruit{
  ...
}

5. Generate the Javadocs

Instruct Maven to generate the Javadocs for the project by running the following command:

mvn javadoc:javadoc

And that's it! You should be good to go.

References:

• Syntaxhighlighter homepage: http://alexgorbatchev.com/SyntaxHighlighter/
• Maven Javadoc plugin docs: http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html