Skip to content

Latest commit

 

History

History
225 lines (183 loc) · 9.38 KB

README-0.30.md

File metadata and controls

225 lines (183 loc) · 9.38 KB
Raw

Codesnippet Javadoc Doclet 0.30

This is documentation for older version of the Codesnippet Javadoc Doclet. Read the latest README to follow the most recent trends and suggestions.

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

The bits of the codesnippet-doclet are being uploaded to Maven central. 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.30</version> <!-- or any newer version -->
     </docletArtifact>
     <!-- if you want to reference snippets from your test directory, also include -->
     <additionalparam>-snippetpath src/test/java</additionalparam>
    </configuration>
</plugin>

Use in a Gradle Project

Add the doclet to your Gradle javadoc configuration

configurations {
    snippetdoclet
}

dependencies {
    snippetdoclet group: 'org.apidesign.javadoc', name: 'codesnippet-doclet', version: '0.31'
}

javadoc {
    options.doclet = "org.apidesign.javadoc.codesnippet.Doclet"
    options.docletpath = configurations.snippetdoclet.files.asType(List)
    options.addStringOption "snippetpath", "src/test/java"
}

Use with JDK9+

The Codesnippet doclet supports JDK9+ and newer as well as JDK8. There have been major changes to the javadoc API in JDK9, but it seems I found a way to support older as well as new style. In order to use the doclet on JDK9+ it may however be necessary to open up one implementation package and pass -J--add-opens=jdk.javadoc/com.sun.tools.javadoc.main=ALL-UNNAMED parameter when invoking the javadoc command. In case of Maven one can do it like this:

<configuration>
    <doclet>org.apidesign.javadoc.codesnippet.Doclet</doclet>
    <docletArtifact>
        <groupId>org.apidesign.javadoc</groupId>
        <artifactId>codesnippet-doclet</artifactId>
        <version>0.30</version>
    </docletArtifact>
    <additionalJOptions>
        <opt>-J--add-opens=jdk.javadoc/com.sun.tools.javadoc.main=ALL-UNNAMED</opt>
    </additionalJOptions>
</configuration>

The doclet can run without the opened package, but some features (like copying doc-files) may not work properly.

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.

Hide @Deprecated Classes

The code snippet doclet can, since version 0.11, exclude Javadoc elements annotated by some annotation from the Javadoc. This is especially useful with java.lang.Deprecated annotation, by using:

$ javadoc \
  -doclet org.apidesign.javadoc.codesnippet.Doclet \
  -docletpath path/to/downloaded/codesnippet-doclet.jar \
  -hiddingannotation java.lang.Deprecated

one can eliminate deprecated fields and methods from the Javadoc and also hide classes and interfaces from the Javadoc overview (however their individual HTML pages still remain in Javadoc for those who keep permanent links to them). One can use the -hiddingannotation parameter with other annotations as well and even repeat the parameter multiple times to hide multiple annotations at once.

Linking types

The doclet searches existing import statements in the code snippet and tries to link the Java files in the package. When a matching type is found, the identifier is wrapped with @link. Note that the linking is best-effort only and when the type is not found, a warning message is logged Tag @link: reference not found: <classname>.

You can suppress the warning by passing the parameter -suppressMissingLinkWarnings as shown below. This parameter will convert the warning to an informational message, so, you can continue to see the types that are missing links and not fail the build on warnings if failOnWarnings flag is set in your javadoc configuration.

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

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