How to provide external file based code snippets using a Gradle Java project

Question

I am trying to use code snippets using external file. My documentation looks like this:

/**
 * The following method uses the {@code HttpRequest.GET()} method. Please use it like follows:
 * {@snippet class="ShowHttpClientExamples" region="restServicePost"}
 */

I have a directory named snippets-file in the directory src/java/ and in my build.gradle file I have he following code in the javadoc task :

javadoc {
    doFirst {
        options.addStringOption('-snippet-path', "${rootDir}/src/java/snippet-files")
    }
}

I am trying to specify the snippet-path for the javadoc task.
When I execute the task I get the error that class ShowHttpClientExamples isn't found on the source path or snippet path.

I tried to create a directory first and then a package named snippet-files inside the package containing the class containing the method documented with the @snippet tag, all according to the guide. I still get the same error.

How to I use code snippets using external code file in Gradle with Application plugin?

I tried to follow this blog which is for Maven and tried to adapt for my case but the error still persists.

Answer 1

To use code snippets using external files in Gradle with the Application plugin, you need to follow these steps:

Create a directory to store your snippet files. For example, you can create a directory named snippets at the root of your project.

Create a package structure that matches the package structure of the class that contains the code snippet. For example, if the class that contains the code snippet is in the package com.example.myapp, create a directory structure snippets/com/example/myapp.

Create a file in the directory structure you created in step 2 that contains the code snippet. For example, if the code snippet is named restServicePost, create a file named restServicePost.java in the snippets/com/example/myapp directory.

Add the --module-path and --add-modules options to the javadoc task in your build.gradle file to include the external files in the classpath:

javadoc {
    doFirst {
        options.addStringOption('-module-path', "${rootDir}/snippets")
        options.addStringOption('-add-modules', 'ALL-SYSTEM')
    }
}

In the Javadoc comment, use the @snippet tag to reference the code snippet. For example:

    /**
 * The following method uses the {@code HttpRequest.GET()} method. Please use it like follows:
 * {@snippet class="com.example.myapp.ShowHttpClientExamples" region="restServicePost"}
 */

Run the javadoc task to generate the documentation. By following these steps, you should be able to use code snippets using external files in Gradle with the Application plugin.