CoreJavadocOptions Cannot Set Array of Values for Option Property

Help/Discuss
1

I’m using a GitHub hosted project that’s developed a JavaDoc doclet. In my Gradle build file, I’ve created a task to configure and run the doclet (and generate the associated JavaDoc):

task generateRestApiDocs(type: Javadoc) {
    source = sourceSets.main.allJava

// Save the output into web directory under apidocs
    def file = new File("web/apidocs")
    destinationDir = file

    options.classpath = configurations.doclet.files.asType(List)
        options.docletpath = configurations.doclet.files.asType(List)

       // Use the Swagger JAXRS doclet
        options.doclet = "com.carma.swagger.doclet.ServiceDoclet"
}

One of the options of the Doclet I’m using is to pass a list of packages to exclude from documentation generation.

It’s property is called: excludeResourcePrefixes.

Internally, the library is doing the following to extract the values and use them:

} else if (option[0].equals("-excludeResourcePrefixes")) {
	parsedOptions.excludeResourcePrefixes.addAll(asList(copyOfRange(option, 1, option.length)));

The options property above is the default String[][] found on JavaDoc’s RootDoc.java#options. According to RootDoc.java comments, options passed in as an array will be treated as String[][]:

    /**
     * Command line options.
     * <p>
     * For example, given:
     * <pre>
     *     javadoc -foo this that -bar other ...</pre>
     *
     * this method will return:
     * <pre>
     *      options()[0][0] = "-foo"
     *      options()[0][1] = "this"
     *      options()[0][2] = "that"
     *      options()[1][0] = "-bar"
     *      options()[1][1] = "other"</pre>
     *
     * @return an array of arrays of String.
     */
    String[][] options();

So what I need to do is pass an array of values for the excludeResourcePrefixes property.

I tried several different addXX methods on the CoreJavadocOptions.java class but none of them seem to work completely correct.

What I need in my JavaDoc options “file” is:

-excludeResourcePrefixes com.me.server.rest.administration com.me.server.rest.workspace

Here is what I tried:

options.addStringsOption("excludeResourcePrefixes").setValue([
            "com.me.server.rest.administration",
            "com.me.server.rest.workspace"
    ])

Creates:

-excludeResourcePrefixes 'com.me.server.rest.administration:com.me.server.rest.workspace'

Won’t work b/c we need items to be separated and also not wrapped as a single string (e.g. ‘’).

Next:

options.addStringsOption("excludeResourcePrefixes", " ").setValue([
            "com.me.server.rest.administration",
            "com.me.server.rest.workspace"
    ])

This produces and won’t work again because the items are being treated as a single string:

-excludeResourcePrefixes 'com.me.server.rest.administration com.me.server.rest.workspace'

Unfortunately, the only thing I could get to work was:

options.addMultilineStringsOption("excludeResourcePrefixes").setValue([
            "com.me.server.rest.administration",
            "com.me.server.rest.workspace"
    ])

This produced:

-excludeResourcePrefixes 'com.me.server.rest.administration'
-excludeResourcePrefixes 'com.me.server.rest.workspace'

While not ideal, it does work because luckily Swagger-Jaxrs-Doclet’s DocletOptions.java class will loop through all the options and will just add any duplicate options to the existing excludes collection versus overwriting it:

} else if (option[0].equals("-excludeResourcePrefixes")) {
	parsedOptions.excludeResourcePrefixes.addAll(asList(copyOfRange(option, 1, option.length)));

So my ultimate question, is how can I use CoreJavadocOptions.java to add an ‘array’ of command-line arguments to the JavaDoc options object so that they will be correctly “arrayed” by the RootDoc class?

In some ways I think a new addArrayOption(String name, List values) would be a worthy addition to the CoreJavadocOptions.java class.

2

You could try using a custom delimiter.

options.addStringsOption('excludeResourcePrefixes', "' '").setValue(['com.me.server.rest.administration', 'com.me.server.rest.workspace'])

produces the following

-excludeResourcePrefixes 'com.me.server.rest.administration' 'com.me.server.rest.workspace'
3

@mark_vieira Thanks for the quick reply!

So I tried your suggestion. And indeed it produces the correct javadoc options:

-excludeResourcePrefixes 'com.me.server.rest.administration' 'com.me.server.rest.workspace'

However, I updated the 3rd party library’s source code to print out the values it was receiving and it got:

} else if (option[0].equals("-excludeResourcePrefixes")) {
	System.out.println("RESOURCES START");
	for(int i=0; i < option.length; i++) {
		System.out.println("Option/Value: " + option[i]);
	}
	System.out.println("RESOURCES END");
	parsedOptions.excludeResourcePrefixes.addAll(asList(copyOfRange(option, 1, option.length)));
}

But my printout shows:

RESOURCES START
Option/Value: -excludeResourcePrefixes
Option/Value: com.me.server.rest.administration
RESOURCES END

So I’m not sure where to go from here…whatever is reading the JavaDoc options and converting it into the String[][] for the RootDoc element is not correctly grabbing the “array” of values.

Here is the library’s first use of RootDoc/options:

	/**
	 * Generate documentation here.
	 * This method is required for all doclets.
	 * @param doc The root doc
	 * @return true on success.
	 */
	public static boolean start(RootDoc doc) {
		String[][] additionalParams = doc.options();

		for(String[] strings : additionalParams)
			for(String str : strings) {
				System.out.println("Option/Value: " + str);
			}

		sanitizeAdditionalParams(additionalParams);
		DocletOptions options = DocletOptions.parse(additionalParams);
		return new JaxRsAnnotationParser(options, doc).run();
	}

Here is the printout I get:

...
Option/Value: -doctitle
Option/Value: ME REST API
Option/Value: -excludeResourcePrefixes
Option/Value: com.me.server.rest.administration
Option/Value: -quiet
Option/Value: -sortResourcesByPath
...

Is this perhaps a bug in the Gradle JavaDocTask that passes the options into the RootDoc? Or a bug perhaps with JavaDoc library itself?

4

Gradle doesn’t populate RootDoc we simply generate an options file and pass it as an argument to the javadoc executable. You can use the --debug command line option to see the exact command Gradle is executing. You may want to try playing around with the options file Gradle generates manually to see if you can get it to work properly. Perhaps try omitting the quotes around the package names. Either way, I expect it’s an issue with javadoc not parsing the options file properly. Might also try comparing using the options file vs adding the options to the command line to see if there is a difference.