Hi Adam,
On Jul 28, 2008, at 4:17 AM, Adam Murdoch wrote:
Hi,
I'd like to do some work on the documentation for the gradle api,
starting with some javadocs. Given that the core api is java and
that groovydoc doesn't do anything much, I think it would be good
to generate javadoc for the gradle api alongside (or possibly
instead of) the groovydoc that we include in the distribution.
It would be so valuable to have good javadoc. Our user's guide is
linking to this doc to point out detailed information. But this
information is mostly not generated right now.
We should use solely javadoc. The problem is that many of our tasks
(where the doc is most important) are still in Groovy. So we can't
generate any reasonable doc for them right now. But they are going to
be refactored into Java rather soon. At the end of the day there will
be a handful of Groovy classes left. And even those we could refactor
into Java (for the purpose of having javadoc) by extending
GroovyObjectSupport.
Is this a good change to make, and if so, is it something the
groovy plugin should do (ie does every groovy project have this
problem), or is it something specific to gradle's build?
It affects all Groovy projects. Groovydoc is simply not production
ready. See http://www.nabble.com/Groovydoc-to17880778.html#a17880778
The Groovydoc tool should be able to generate complete html doc for
Java and Groovy classes. That would be required for Groovy's seamless
integration with Java on this level. Groovydoc accepts Java and
Groovy classes as input but the result is pretty worthless. And
nobody seems currently working on this to improve the situation.
At the moment you can't produce resonable documentation for Groovy
code. This is a serious issue. So what the Groovy plugin can do is
either generating rather worthless Groovydoc docs for Java and Groovy
classes. Or to generate classic Javadoc for the Java classes only and
Groovydoc for the Groovy classes (some people might still perceive a
value in having those). Both would live in different folders.
- Hans
--
Hans Dockter
Gradle Project lead
http://www.gradle.org
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
