JavaDoc with CodeSnippet

Adding codesnippets to JavaDocs

For all public facing APIs and classes, we recommend having a descriptive JavaDoc that clearly outlines the purpose of the class or method. Including relevant code samples to show how to use the class or methods in JavaDoc enables users to easily understand how to use the APIs and these samples can demonstrate best practices. If code samples are included in the JavaDoc, when the HTML documentation is generated the code might not be properly encoded and will not be rendered correctly. Another issue with manually writing code samples in JavaDoc is that when the code changes, the doc can become stale. To avoid these issues, we use a tool called codesnippet that can inject code into JavaDoc from a *.java file with proper encoding. This will allow us to write code in a Java file, compile and inject the code samples into JavaDocs.

To use this tool, we will need to perform the following steps:

• In sdk/parents/azure-client-sdk-parent/pom.xml, go to the <reporting> section, find the maven-javdoc-plugin and add the following line under <additionalOptions> tag. -snippetpath ${project.basedir}/sdk/<your-project-directory>/<your-project-artifact>/src/samples/java

• Now, in your project, create a Java file called <service-name>-JavaDocCodeSnippets.java in src/samples/java/<your-root-package-name>/ directory.

• In this file, write Java code samples that you wish to include in the JavaDocs. This code should be compilable. So, you will have to create necessary variables, methods etc. However, these things don't have to be part of the JavaDoc.

• Add a line comment before the start of the sample code as shown below: // BEGIN:

• Add a line comment after the end of the sample code as shown below: // END:

• Now, in your actual JavaDoc section, you can refer to this code snippet as follows:

{@codesnippet codesample-unique-name}

The <codesample-unique-name> should follow the naming pattern outlined in the Java design guidelines.

Example

Let's take a look at how we do this by using App Configuration client library as an example

Update parent pom

In sdk/parents/azure-client-sdk-parent/pom.xml, we added the following line:

-snippetpath ${project.basedir}/sdk/appconfiguration/azure-data-appconfiguration/src/samples/java

Created Java file to host the code samples:

In sdk/appconfig/azure-data-appconfiguration/src/samples/java we created a compilable source file called `ConfigurationClientJavaDocCodeSnippets.java

Added code samples

In this file, we added code samples that we want to include in JavaDocs and wrapped it with line comments to mark the beginning and end of the snippet

public final class ConfigurationClientJavaDocCodeSnippets {

    public ConfigurationClient createAsyncConfigurationClientWithPipeline() {

        String connectionString = getConnectionString();
        // BEGIN: com.azure.data.applicationconfig.configurationclient.pipeline.instantiation
        HttpPipeline pipeline = new HttpPipelineBuilder()
            .policies(/* add policies */)
            .build();

        ConfigurationClient configurationClient = new ConfigurationClientBuilder()
            .pipeline(pipeline)
            .endpoint("https://myconfig.azure.net/")
            .connectionString(connectionString)
            .buildClient();
        // END: com.azure.data.applicationconfig.configurationclient.pipeline.instantiation
        return configurationClient;
    }
}

Note that the class has a new method, a variable declaration connectionString and a return statement. However, none of these will be included in the JavaDoc. The JavaDoc will only include the code that is within the BEGIN and END comments.

HttpPipeline pipeline = new HttpPipelineBuilder()
            .policies(/* add policies */)
            .build();

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
    .pipeline(pipeline)
    .endpoint("https://myconfig.azure.net/")
    .connectionString(connectionString)
    .buildClient();

Using the code snippet in JavaDoc

Now, we want to include this code snippet in ConfigurationClient.java.

To do so, we just add the following line to the class JavaDoc

{@codesnippet com.azure.data.applicationconfig.configurationclient.instantiation}

The complete JavaDoc will look like this:

/**
 * This class provides a client that contains all the operations for {@link ConfigurationSetting ConfigurationSettings}
 * in Azure App Configuration Store. Operations allowed by the client are adding, retrieving, deleting, set read-only
 * status ConfigurationSettings, and listing settings or revision of a setting based on a
 * {@link SettingSelector filter}.
 *
 * <p><strong>Instantiating a synchronous Configuration Client</strong></p>
 *
 * {@codesnippet com.azure.data.applicationconfig.configurationclient.instantiation}
 *
 * <p>View {@link ConfigurationClientBuilder this} for additional ways to construct the client.</p>
 *
 * @see ConfigurationClientBuilder
 */

Generated JavaDoc

When the maven plugin generates the JavaDoc, the {@codesnippet ...} will be replaced by the code sample as shown below: