api documentation

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

api documentation

Adam Murdoch-2
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.

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?


Adam


---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: api documentation

hans_d
Administrator
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


Reply | Threaded
Open this post in threaded view
|

Re: api documentation

Adam Murdoch-2


Hans Dockter wrote:
>
> 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.
>
I might change the groovy plugin to add a 'groovydoc' task, rather than
overriding the 'javadoc' task.


Adam


---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: api documentation

hans_d
Administrator
Hi Adam,

On Jul 28, 2008, at 10:48 AM, Adam Murdoch wrote:

>
>
> Hans Dockter wrote:
>>
>> 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.
>>
> I might change the groovy plugin to add a 'groovydoc' task, rather  
> than overriding the 'javadoc' task.

I think this makes sense. I just had a look at the Groovy Plugin and  
it anyway does not behave as it should I think.

As described in UG chapter 10, a Groovy project can have a main/java  
and a main/groovy folder. The first is treated like a normal Java  
project, the second may contain mixed Java/Groovy code. Therefore the  
Groovy plugin should not remove the javadoc functionality applied  
against the main/java folder (what it does now). So we should have a  
javadoc running against the Java classes in main/java and main/groovy  
and a groovydoc running against the groovy classes in main/groovy.

I have created a Jira: http://jira.codehaus.org/browse/GRADLE-168

- Hans

>
>
> Adam
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>    http://xircles.codehaus.org/manage_email
>
>

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email