[GRADLE-1563] Javadoc Plugin does not generate correct command line options for tags and targlets Created: 19/May/11  Updated: 04/Jan/13  Resolved: 20/Dec/11

Status: Resolved
Project: Gradle
Affects Version/s: 1.0-milestone-3
Fix Version/s: 1.0-milestone-8

Type: Bug
Reporter: Howard M. Lewis Ship Assignee: Peter Niederwieser
Resolution: Fixed Votes: 1

Issue Links:
Duplicate
Duplicates GRADLE-1840 The Javadoc task doesn't handle custo... Resolved

 Description   

I'm attempting to use a custom taglet when generating JavaDoc.

I'm specifying the taglet, the FQCN of my Taglet class:

task aggregateJavadoc(type: Javadoc) {
  description = "Build the aggregated JavaDocs for all modules"
  maxMemory = '512m'
  destinationDir = javadocBuildDir.dir
  configure(options) {
      // overview = new File( projectDir, 'src/javadoc/package.html' )
      // stylesheetFile = new File( projectDir, 'src/javadoc/stylesheet.css' )
      windowTitle = 'Tapestry API Documentation'
      docTitle = "Tapestry JavaDoc ($project.version)"
      bottom = "Copyright &copy; 2003-2011 <a
href=\"http://tapestry.apache.org\">The Apache Software
Foundation</a>."
      use = true
      links = [ 'http://download.oracle.com/javase/6/docs/api/',
'http://download.oracle.com/javaee/6/api/' ]
      // classpath = configurations.javadoc
      verbose = true
      taglets "org.apache.tapestry5.javadoc.TapestryDocTaglet"
  }

  subprojects.each { subProject->

      subProject.sourceSets.each { set ->

          if ("test" != set.name) {
              source set.java

              if (classpath) {
                  classpath += set.classes + set.compileClasspath
              }
              else {
                  classpath = set.classes + set.compileClasspath
              }
          }
      }
  }
}

The generated arguments file shows something odd:

-link 'http://download.oracle.com/javase/6/docs/api/'
-link 'http://download.oracle.com/javaee/6/api/'
-use
-doctitle 'Tapestry JavaDoc (unspecified)'
-tags 'org.apache.tapestry5.javadoc.TapestryDocTaglet'
-d '/Users/hlship/workspaces/tapestry/tapestry5/build/documentation/javadocs'

It should not be "-tags", it should be "-taglet". Even "-tags" is
wrong (from javadoc --help):

-tag <name>:<locations>:<header>  Specify single argument custom tags
-taglet                           The fully qualified name of Taglet to register
-tagletpath                       The path to Taglets

In StandardJavadocDocletOptions.java:

   public void setTags(List<String> tags) {
       this.tags.setValue(tags);
   }

   public StandardJavadocDocletOptions tags(List<String> tags) {
       this.tags.getValue().addAll(tags);
       return this;
   }

   public StandardJavadocDocletOptions tags(String... tags) {
       return tags(Arrays.asList(tags));
   }

   public StandardJavadocDocletOptions taglets(String... taglets) {
       return tags(Arrays.asList(taglets));
   }

   public StandardJavadocDocletOptions tagsFile(File tagsFile) {
       return (StandardJavadocDocletOptions) optionFiles(tagsFile);
   }

See also: http://download.oracle.com/javase/1.5.0/docs/tooldocs/solaris/javadoc.html#standard

StandardJavadocDocletOptions is treating tags and taglets like they
were the same thing, they are not.

My workaround is to replace the taglets configuration with:

      addStringOption "taglet",
"org.apache.tapestry5.javadoc.TapestryDocTaglet"

I believe this is a bug. In fact, I think I see several:

1. tags and taglets are not the same, they should be tracked seperately
2. Each tag should be written as its own "-tag xxx:y:z" command line
option (currently, all tags are concatinated and emitted as a single
-tags command line option)
3. Each taglet should be written as its own "-taglet foo.bar.Baz"
command line option

 Comments   
Comment by Steve Ebersole [ 20/Dec/11 ]

I have run into this as well. And worse, there does not appear to be a good work around.

There is the method http://gradle.org/current/docs/javadoc/org/gradle/external/javadoc/MinimalJavadocOptions.html#contributeCommandLineOptions%28org.gradle.process.ExecSpec%29 but I have not found how to actually instantiate one of these http://gradle.org/current/docs/javadoc/org/gradle/process/ExecSpec.html unless I instantiate an Exec task.

I do not see the method "addStringOption" that Howard mentions...

Comment by Peter Niederwieser [ 20/Dec/11 ]

Just call "options.addStringOption()". It's a method on the implementation class, not part of the public API.

Comment by Stefan Simroth [ 02/Feb/12 ]

Great that this will be fixed in the next release and that there exists a workaround!

This did it for me with 1.0-milestone7:

 
javadoc {
  options.addStringOption "taglet", "net.sourceforge.taglets.Taglets"
  options.addStringOption "tagletpath", "rsrc:tools/Javadoc/taglets-2.0.3/taglets.jar"
}

Just FYI, there seems to be a duplicate issue that could also get resolved, see GRADLE-1840

Generated at Wed Jun 30 11:58:43 CDT 2021 using Jira 8.4.2#804003-sha1:d21414fc212e3af190e92c2d2ac41299b89402cf.