yetus-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Grant Henke (JIRA)" <j...@apache.org>
Subject [jira] [Created] (YETUS-627) Doclet does not work with Gradle Javadoc generation
Date Fri, 13 Apr 2018 14:17:00 GMT
Grant Henke created YETUS-627:
---------------------------------

             Summary: Doclet does not work with Gradle Javadoc generation
                 Key: YETUS-627
                 URL: https://issues.apache.org/jira/browse/YETUS-627
             Project: Yetus
          Issue Type: Bug
          Components: Audience Annotations
         Environment: Gradle 4.6, Java 1.8.0_121
            Reporter: Grant Henke


The IncludePublicAnnotationsStandardDoclet does not work with Gradle Javadoc generation,
though it does for Maven in the same project. It appears Maven passes slightly different arguments
to the Javadoc tool. 

In Gradle I configured the Javadoc task to use the Doclet via:
{code:java}
configurations {
   doclet
}

dependencies {
   doclet "org.apache.yetus:audience-annotations:0.7.0"
}

javadoc {
   options.docletpath = configurations.doclet.files.asType(List)
   options.doclet = 'org.apache.yetus.audience.tools.IncludePublicAnnotationsStandardDoclet'
}{code}
Running _gradle javadoc_ results in: 

 
{code:java}
IncludePublicAnnotationsStandardDoclet java.lang.ArrayStoreException: com.sun.proxy.$Proxy2
at java.util.AbstractCollection.toArray(AbstractCollection.java:196) at com.sun.tools.doclets.internal.toolkit.util.IndexBuilder.buildIndexMap(IndexBuilder.java:160)
at com.sun.tools.doclets.internal.toolkit.util.IndexBuilder.<init>(IndexBuilder.java:124)
at com.sun.tools.doclets.internal.toolkit.util.IndexBuilder.<init>(IndexBuilder.java:103)
at com.sun.tools.doclets.formats.html.HtmlDoclet.generateOtherFiles(HtmlDoclet.java:122) at
com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:146)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:82) at
com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:80) at com.sun.tools.doclets.standard.Standard.start(Standard.java:39)
at org.apache.yetus.audience.tools.IncludePublicAnnotationsStandardDoclet.start(IncludePublicAnnotationsStandardDoclet.java:51)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at
java.lang.reflect.Method.invoke(Method.java:498) at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:310)
at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:189) at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:366)
at com.sun.tools.javadoc.Start.begin(Start.java:219) at com.sun.tools.javadoc.Start.begin(Start.java:205)
at com.sun.tools.javadoc.Main.execute(Main.java:64) at com.sun.tools.javadoc.Main.main(Main.java:54)
{code}
 

Digging into the stack trace a bit it appears that the issue comes from building an index
of packages, however Gradle passes the class files to Javadoc and does not pass packages.
This is a valid way to generate Javadoc as documented here: [https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#documentingclasses]

The Javadoc options Gradle generates are (with path substitutions): 

 
{code:java}
-classpath '/some/classpath/paths/...'
-d '/some/destination/directory'
-doclet 'org.apache.yetus.audience.tools.IncludePublicAnnotationsStandardDoclet'
-docletpath '/path/to/audience-annotations-0.7.0.jar'
-doctitle 'some API'
-quiet 
-windowtitle 'some API'
'/path/to/some/Class.java'
'/path/to/some/Class2.java'
'/path/to/some/Class3.java'
...{code}
There is no great way to add packages to the Javadoc options output in Gradle, but one hacky
solution does allow it to successfully generate Javadocs. Forcing a valid package name into
the options by passing it with an option that takes no arguments will allow the task to succeed. 

In Gradle I added:

 
{code:java}
javadoc {
   ...
   // A Javadoc option that takes no parameter, 
   // and a valid package as the parameter.
   options.addStringOption("notimestamp", "some.valid.package")
}{code}
This results in the the following javadoc options:

 

 
{code:java}
-classpath '/some/classpath/paths/...'
-d '/some/destination/directory'
-doclet 'org.apache.yetus.audience.tools.IncludePublicAnnotationsStandardDoclet'
-docletpath '/path/to/audience-annotations-0.7.0.jar'
-doctitle 'some API'
-notimestamp 'some.valid.package'
-quiet 
-windowtitle 'some API'
'/path/to/some/Class.java'
'/path/to/some/Class2.java'
'/path/to/some/Class3.java'
...
{code}
Note: The packages would generally come just before the list of classes per the documentation,
but this seams to work for some reason. (https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#documentingboth)

 

When running gradle javadoc there may be a warning like below when using this hacky workaround:
{code:java}
javadoc: warning - No source files for package some.valid.package
{code}
 

 

 



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

Mime
View raw message