excludeResourcePrefixes Option Not Supporting Multiple Objects

[nkoterba]

I've noticed that in DocletOptions.java many of the options accept an array of items, e.g.:

            } else if (option[0].equals("-parameterNameAnnotations")) {
                parsedOptions.parameterNameAnnotations.addAll(asList(copyOfRange(option, 1, option.length)));
            } else if (option[0].equals("-stringTypePrefixes")) {
                parsedOptions.stringTypePrefixes.addAll(asList(copyOfRange(option, 1, option.length)));
            } else if (option[0].equals("-excludeClassTags")) {
                parsedOptions.excludeClassTags.addAll(asList(copyOfRange(option, 1, option.length)));
            } else if (option[0].equals("-excludeOperationTags")) {
                parsedOptions.excludeOperationTags.addAll(asList(copyOfRange(option, 1, option.length)));
            } else if (option[0].equals("-excludeFieldTags")) {

However, I'm having difficulty passing a list of resources to exclude. I'm using gradle and trying to do this:

    options.addStringOption("excludeResourcePrefixes",
            "com.me.server.rest.administration com.me.server.rest.workspace");

I've spent ~3 hours now trying to figure out the correct syntax (do I use [], do I use spaces, etc.). I've looked at the JavaDocOptions classes and it looks like addStringOption is the correct method.

According to the documentation on JavaDoc's RootDoc class:

    /**
     * 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();

Thus I assumed that just space-separating my list of classes to exclude would work. However, when I put a print statement in the DocletOptions.java class, I get the following output: Code in DocletOptions.java:

} 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)));

Result is:

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

Thus, the value is not being turned into an array of String values and the AddAll method below adds an invalid string.

I believe the options object (string[][]) used in DocletOptions is coming directly from JavaDoc source and via the Gradle JavaDocTask so I'm worried this may be an error somewhere other than the swagger-jaxrs-doclet.

Has anybody been able to successfully pass an array of values to any of this Doclet's plugins?

My fallback is to use the @hidden or @exclude JavaDoc annotations but we have lots of classes to exclude and this could get tedious really fast.

[nkoterba]

So I've figured out a solution. It's definitely an issue with the Gradle JavaDocTask plugin not really providing any means to pass an "array" of values into a JavaDoc options property.

NOTE, sadly, there is no easy options.addXXX(name, array) method on the JavaDocOptions class.

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:

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

Still not right. What we really need is:

-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)));

Really, it would be nice if the Gradle team exposed a method to allow setting or passing an array of values for an option instead of methods that turn the array into a single string, but at least for my current needs the solution posted above works.

[nkoterba]

I posted this issue/question at the Gradle forums: https://discuss.gradle.org/t/corejavadocoptions-cannot-set-array-of-values-for-option-property/9820

[nkoterba]

Based on a response from the Gradle team: https://discuss.gradle.org/t/corejavadocoptions-cannot-set-array-of-values-for-option-property/9820

It sounds like one way to accomplish the above is:

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

which produces:

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

As such, I'm closing this issue...I don't necessarily like the "method" gradle suggests, but it does work. It's just not very intuitive.