How to have javadoc reference a taglet artifact?

Help/Discuss
1

I’m trying to port a Maven build to Gradle. I wrote a custom taglet in a separate project that this project references as a GAV (in the Maven build, at least). I’m trying to figure out how to translate this to the javadoc task in Gradle. I see the “tagletPath” list property, but that’s just a list of Files. How can I reference an artifact here?

If it matters, the reference in the original maven-javadoc-plugin looks like this:

                <tagletArtifacts>
                    <tagletArtifact>
                        <groupId>com.att.detsusl.taglets</groupId>
                        <artifactId>validationJavadocTaglet</artifactId>
                        <version>0.0.1-SNAPSHOT</version>
                    </tagletArtifact>
                </tagletArtifacts>
2

I’m guessing you’d set the tagletPath eg:

configurations {
    taglet
} 
dependencies {
    taglet 'com.att.detsusl.taglets:validationJavadocTaglet:0.0.1-SNAPSHOT' 
} 
javadoc {
   options {
      tagletPath configurations.taglet.files
   } 
}
3

When I first saw this reply, I realized you were surely right. I’ve been away from this for a while, and forgot about how to use configurations and “.files”.

Unfortunately, although this produces what I expect, it still fails.

I have the following:

configurations {
    taglet
}

dependencies {
    taglet "com.att.detsusl.taglets:validationJavadocTaglet:0.0.1-SNAPSHOT"
}

javadoc {
    options {
        addStringOption("top").value  = "Unified Service Layer - top"
        bottom "Unified Service Layer - bottom"
        windowTitle "Unified Service Layer - windowtitle"
        docTitle "Unified Service Layer - title"
        footer "Unified Service Layer - footer"
        header "Unified Service Layer - header"
        setMemberLevel JavadocMemberLevel.PUBLIC

        addStringOption('Xdoclint:none')
        
        taglets "com.att.det.taglet.ValidationConstraintsTaglet", "com.att.det.taglet.ValidationConstraintsCombinedTaglet"

        tagletPath configurations.taglet.files
    }
}

When I run “gradle javadoc”, I get this:

A problem occurred evaluating root project ‘usl-parent’.

Could not find method tagletPath() for arguments [[….m2\repository\com\att\detsusl\taglets\validationJavadocTaglet\0.0.1-SNAPSHOT\validationJavadocTaglet-0.0.1-SNAPSHOT.jar, ….m2\repository\org\hibernate\hibernate-validator\5.4.1.Final\hibernate-validator-5.4.1.Final.jar, …]] on object of type org.gradle.external.javadoc.StandardJavadocDocletOptions.

I can’t tell from this output whether it truly created “File” objects or just Strings. I can see from the “StandardJavadocDocletOptions” class that it requires File objects. I would assume that “files” would do that, but I don’t know what might be wrong here.

4

Calling files on a configuration returns a Set<File>, but tagletPath expects a List<File> or varargs File..., so your problem is likely with the wrapper, not the contents.

5

Hmm, surprised that you can’t get yourself over the line on this one

Try tagletPath(configurations.taglet.files as File[]) or similar

6

I don’t get to Groove every often (invented a new verb there :slight_smile: ), so I didn’t think of this.

From a practical point of view, would it be reasonable to suggest that DSL functions (or functions that are likely to be called from a Gradle build script) that take a “List” parameter should also have a “Set” version, as there are likely many cases where “.files” would be the input for it?

7

I’d say the api would be more “gradley” if it accepted FileCollection in which case you could just pass configurations.taglet

(invented an adjective there :smile:)