Javadoc doclet to include real code snippets in the documentation
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
doclet Special method to find annotations of an element Jan 11, 2017
testing
.gitignore
.travis.yml
COPYING
LICENSE
README.md
pom.xml [maven-release-plugin] prepare for next development iteration Jul 27, 2016

README.md

Codesnippet Javadoc Doclet

Build Status

Say farewell to broken or outdated samples in your Javadoc! The Codesnippet Doclet helps you include real code snippets in the documentation ensuring they are always compilable. If you make the samples part of your test suite, even ensuring they execute properly.

Use org.apidesign.javadoc.codesnippet.Doclet to increase quality of your Javadoc! The doclet uses the same infrastructure as was used when publishing Practical API Design and 20 API Paradoxes books making sure all code samples were correct, compilable and printed with pretty syntax coloring.

How does it work?

The Codesnippet Doclet introduces new tag codesnippet that allows you to reference real code snippets in your project. Identify the snippets in your code and then reference them from a Javadoc:

/** My sample class.
 * {@codesnippet sample1}
 * Rest of the text.
 */
public class SampleClass {
    private SampleClass() {
    }

    private static void sample1() {
        // BEGIN: sample1
        int x = 42;
        // END: sample1
    }
}

The rendered Javadoc for the class will include:

My sample class.
int x = 42;
Rest of the text.

Identify important pieces of code and add line comment BEGIN: samplename before start of each snippet. Put END: samplename or FINISH: samplename at the end of the code snippet. Then you can reference the snippet in Javadoc with the @codesnippet tag.

Having correct samples in Javadoc has never been easier!

Use in a Maven Project

Add the doclet to your Maven Javadoc plugin configuration (as done here):

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-javadoc-plugin</artifactId>
   <version>2.10.3</version>
   <configuration>
     <doclet>org.apidesign.javadoc.codesnippet.Doclet</doclet>
     <docletArtifact>
       <groupId>org.apidesign.javadoc</groupId>
       <artifactId>codesnippet-doclet</artifactId>
       <version>0.10</version> <!-- or any newer version -->
     </docletArtifact>
     <!-- if you want to reference snippets from your test directory, also include -->
     <additionalparam>-snippetpath "${basedir}/src/test/java"</additionalparam>
    </configuration>
</plugin>

Use with Command Line Javadoc Tool

Get the Codesnippet Doclet binary. Preferrably from the Maven Central. Invoke your Javadoc as usually plus add following parameters:

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  -snippetpath src/test:src/sample # in case you want to pick the samples from other locations as well

Embed Snippets in API files

You may prefer to include code snippets into the same files as your API to improve life of people who browse the source in an IDE. In such case follow the sample described in EmbeddingSampleCode file - e.g. add yet another class to the end of your file, give it a special name (for example MySnippet) and put code snippet there.

In addition to that you can reference your class as {@link MySnippet} if you pass in additional parameter to specify format of your snippet classes:

$ javadoc \
  -snippetclasses .*Snippet.*

The doclet will then convert all links to classes that match such pattern into appropriate code snippets.

You may want to exclude these sample classes from the final JAR file. The easiest way to do so is to configure your JAR packager to ignore such files:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>2.6</version>
    <configuration>
        <excludes>
            <exclude>**/*Snippet*.class</exclude>
        </excludes>
    </configuration>
</plugin>

Real life example is available here.

Maximum line length

By default Codesnippet will raise an error when the line length of the snippet exceeds 80 characters. This default can be altered by specifying the maximum line length as parameter, like demonstrated below.

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  -maxLineLength 120

Verify @since tag

Quality of an API documentation can be increased if one requires that every API element has a @since tag. To verify such statement an automated tool is needed. This doclet is such tool. Just pass verifysincepresent parameter

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  -verifysincepresent

and warning will be printed for every element without the @since tag.

License

Feel free to use the Codesnippet Doclet binary to generate any public or private Javadoc. If you include the Codesnippet Doclet in your product or make modifications to it, please obey its GPL 3.0 license.

Projects Using Codesnippet Doclet