headers
Hans Dockter | 17 Jun 10:51

[groovy-dev] Groovydoc

I think it is really a critical problem that the groovydoc tool is  
not production ready.

I guess the way people use Groovy is shifting: from internal and  
experimental to writing production code. But if you want to ship your  
production code and your production code contains an API there is no  
possibility to generate reasonable API documentation for it. I have  
this problem with Gradle and it is a big problem for my users. They  
have to look into the source code to get the information they need  
(maybe this is a good way to recruit developers ;)). In a commercial  
context this problem would be even worse as customers simply expect  
an API doc. It's also kind of tricky, as on first sight one thinks,  
aha, there is Groovydoc so everything is fine. Until you discover,  
may be even late in the process, that there are major problems.

So what are the major problems:

No documentation is generated for fields and properties and  
inheritance is not taken into considerations. Which makes the  
generated docs pretty worthless.

http://jira.codehaus.org/browse/GROOVY-2762
http://jira.codehaus.org/browse/GROOVY-2909

GMaven uses the javadoc tool against the Java stubs. But this does  
not solve the problem either, as the comments on the (private) fields  
are not passed over to the getter and setter methods.

- Hans
(Continue reading)

Permalink | Reply |
headers
Hans Dockter | 17 Jun 13:45

Re: [groovy-dev] Groovydoc

My conclusion is misssing :)

It would be very cool if Groovydoc could be improved for Groovy 1.6  
final.

- Hans

On Jun 17, 2008, at 10:52 AM, Hans Dockter wrote:

> I think it is really a critical problem that the groovydoc tool is  
> not production ready.
>
> I guess the way people use Groovy is shifting: from internal and  
> experimental to writing production code. But if you want to ship  
> your production code and your production code contains an API there  
> is no possibility to generate reasonable API documentation for it.  
> I have this problem with Gradle and it is a big problem for my  
> users. They have to look into the source code to get the  
> information they need (maybe this is a good way to recruit  
> developers ;)). In a commercial context this problem would be even  
> worse as customers simply expect an API doc. It's also kind of  
> tricky, as on first sight one thinks, aha, there is Groovydoc so  
> everything is fine. Until you discover, may be even late in the  
> process, that there are major problems.
>
> So what are the major problems:
>
> No documentation is generated for fields and properties and  
> inheritance is not taken into considerations. Which makes the  
> generated docs pretty worthless.
(Continue reading)

Permalink | Reply |
headers
Jeremy Rayner | 17 Jun 16:28

Re: [groovy-dev] Groovydoc

Completely agree.  Unfortunately my day job takes me away from Groovy work
which is the only reason why progress stopped. 

I'll be happy to help and advise anyone who'd like to add these features to Groovydoc.

Cheers
Jez

On Tue, Jun 17, 2008 at 12:45 PM, Hans Dockter <mail-+1IceoBHrC2pwFb5G8XvHQ@public.gmane.org> wrote:
My conclusion is misssing :)

It would be very cool if Groovydoc could be improved for Groovy 1.6 final.

- Hans


On Jun 17, 2008, at 10:52 AM, Hans Dockter wrote:

I think it is really a critical problem that the groovydoc tool is not production ready.

I guess the way people use Groovy is shifting: from internal and experimental to writing production code. But if you want to ship your production code and your production code contains an API there is no possibility to generate reasonable API documentation for it. I have this problem with Gradle and it is a big problem for my users. They have to look into the source code to get the information they need (maybe this is a good way to recruit developers ;)). In a commercial context this problem would be even worse as customers simply expect an API doc. It's also kind of tricky, as on first sight one thinks, aha, there is Groovydoc so everything is fine. Until you discover, may be even late in the process, that there are major problems.

So what are the major problems:

No documentation is generated for fields and properties and inheritance is not taken into considerations. Which makes the generated docs pretty worthless.

http://jira.codehaus.org/browse/GROOVY-2762
http://jira.codehaus.org/browse/GROOVY-2909

GMaven uses the javadoc tool against the Java stubs. But this does not solve the problem either, as the comments on the (private) fields are not passed over to the getter and setter methods.

- Hans

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





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





--
Groovy Engineer http://searchgroovy.org
http://javanicus.com/blog2
Permalink | Reply |
headers
Hans Dockter | 18 Jun 07:30

Re: [groovy-dev] Groovydoc


On Jun 17, 2008, at 4:28 PM, Jeremy Rayner wrote:

> Completely agree.  Unfortunately my day job takes me away from  
> Groovy work
> which is the only reason why progress stopped.
>
> I'll be happy to help and advise anyone who'd like to add these  
> features to Groovydoc.

Wouldn't that be something nice for a summer of code task?

Another cool tool would be generating cross source references for  
Groovy like JXR (http://maven.apache.org/plugins/maven-jxr-plugin).

- Hans

>
>
> Cheers
> Jez
>
> On Tue, Jun 17, 2008 at 12:45 PM, Hans Dockter <mail@...>  
> wrote:
> My conclusion is misssing :)
>
> It would be very cool if Groovydoc could be improved for Groovy 1.6  
> final.
>
> - Hans
>
>
> On Jun 17, 2008, at 10:52 AM, Hans Dockter wrote:
>
> I think it is really a critical problem that the groovydoc tool is  
> not production ready.
>
> I guess the way people use Groovy is shifting: from internal and  
> experimental to writing production code. But if you want to ship  
> your production code and your production code contains an API there  
> is no possibility to generate reasonable API documentation for it.  
> I have this problem with Gradle and it is a big problem for my  
> users. They have to look into the source code to get the  
> information they need (maybe this is a good way to recruit  
> developers ;)). In a commercial context this problem would be even  
> worse as customers simply expect an API doc. It's also kind of  
> tricky, as on first sight one thinks, aha, there is Groovydoc so  
> everything is fine. Until you discover, may be even late in the  
> process, that there are major problems.
>
> So what are the major problems:
>
> No documentation is generated for fields and properties and  
> inheritance is not taken into considerations. Which makes the  
> generated docs pretty worthless.
>
> http://jira.codehaus.org/browse/GROOVY-2762
> http://jira.codehaus.org/browse/GROOVY-2909
>
> GMaven uses the javadoc tool against the Java stubs. But this does  
> not solve the problem either, as the comments on the (private)  
> fields are not passed over to the getter and setter methods.
>
> - Hans
>
> --
> Hans Dockter
> Gradle Project lead
> http://www.gradle.org
>
>
>
>
>
> ---------------------------------------------------------------------
> 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
>
>
>
>
>
> -- 
> Groovy Engineer http://searchgroovy.org
> http://javanicus.com/blog2

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

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

    http://xircles.codehaus.org/manage_email
Permalink | Reply |
headers
Russel Winder | 18 Jun 07:55

Re: [groovy-dev] Groovydoc

On Wed, 2008-06-18 at 07:30 +0200, Hans Dockter wrote:
> On Jun 17, 2008, at 4:28 PM, Jeremy Rayner wrote:
> 
> > Completely agree.  Unfortunately my day job takes me away from  
> > Groovy work
> > which is the only reason why progress stopped.
> >
> > I'll be happy to help and advise anyone who'd like to add these  
> > features to Groovydoc.
> 
> Wouldn't that be something nice for a summer of code task?

Only if we want to wait till 2009 and even then there are no
certainties.

If we want GroovyDoc to do as good a job for Groovy as JavaDoc does for
Java then we are going to have to do it ourselves.

My problem with Gant is that JavaDoc documents the three Java files
nicely but The GroovyDoc of the Groovy and Java code is very incomplete.

What I really want is to only need the GroovyDoc and to be able not to
generate the JavaDoc.  The single biggest problem of the moment is that
the overview.html file and the package.html files are not processed by
GroovyDoc in the same way they are with JavaDoc.

> Another cool tool would be generating cross source references for  
> Groovy like JXR (http://maven.apache.org/plugins/maven-jxr-plugin).

Is there an Ant version of this?  Currently the Groovy build is Ant
based so Maven plugins are not that useful.

--

-- 
Russel.
====================================================
Dr Russel Winder                 Partner

Concertant LLP                   t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road,              f: +44 8700 516 084
London SW11 1EN, UK.             m: +44 7770 465 077
Permalink | Reply |
headers
Hans Dockter | 18 Jun 07:58

Re: [groovy-dev] Groovydoc


On Jun 18, 2008, at 7:55 AM, Russel Winder wrote:

> On Wed, 2008-06-18 at 07:30 +0200, Hans Dockter wrote:
>> On Jun 17, 2008, at 4:28 PM, Jeremy Rayner wrote:
>>
>>> Completely agree.  Unfortunately my day job takes me away from
>>> Groovy work
>>> which is the only reason why progress stopped.
>>>
>>> I'll be happy to help and advise anyone who'd like to add these
>>> features to Groovydoc.
>>
>> Wouldn't that be something nice for a summer of code task?
>
> Only if we want to wait till 2009 and even then there are no
> certainties.
>
> If we want GroovyDoc to do as good a job for Groovy as JavaDoc does  
> for
> Java then we are going to have to do it ourselves.
>
> My problem with Gant is that JavaDoc documents the three Java files
> nicely but The GroovyDoc of the Groovy and Java code is very  
> incomplete.
>
> What I really want is to only need the GroovyDoc and to be able not to
> generate the JavaDoc.  The single biggest problem of the moment is  
> that
> the overview.html file and the package.html files are not processed by
> GroovyDoc in the same way they are with JavaDoc.
>
>> Another cool tool would be generating cross source references for
>> Groovy like JXR (http://maven.apache.org/plugins/maven-jxr-plugin).
>
> Is there an Ant version of this?  Currently the Groovy build is Ant
> based so Maven plugins are not that useful.

I don't know if there is an Ant Version. But you can use JXR directly  
via Java/Groovy.

- Hans

>
> -- 
> Russel.
> ====================================================
> Dr Russel Winder                 Partner
>
> Concertant LLP                   t: +44 20 7585 2200, +44 20 7193 9203
> 41 Buckmaster Road,              f: +44 8700 516 084
> London SW11 1EN, UK.             m: +44 7770 465 077

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

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

    http://xircles.codehaus.org/manage_email
Permalink | Reply |
headers
Russel Winder | 18 Jun 08:02

Re: [groovy-dev] Groovydoc

On Wed, 2008-06-18 at 07:58 +0200, Hans Dockter wrote:
> On Jun 18, 2008, at 7:55 AM, Russel Winder wrote:
> 
> > On Wed, 2008-06-18 at 07:30 +0200, Hans Dockter wrote:

> >> Another cool tool would be generating cross source references for
> >> Groovy like JXR (http://maven.apache.org/plugins/maven-jxr-plugin).
> >
> > Is there an Ant version of this?  Currently the Groovy build is Ant
> > based so Maven plugins are not that useful.
> 
> I don't know if there is an Ant Version. But you can use JXR directly  
> via Java/Groovy.

That works for me :-)

Though we must make sure it doesn't become a required jar for the Groovy
distribution.

--

-- 
Russel.
====================================================
Dr Russel Winder                 Partner

Concertant LLP                   t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road,              f: +44 8700 516 084
London SW11 1EN, UK.             m: +44 7770 465 077
Permalink | Reply |
headers
Hans Dockter | 18 Jun 08:16

Re: [groovy-dev] Groovydoc


On Jun 18, 2008, at 8:02 AM, Russel Winder wrote:

> On Wed, 2008-06-18 at 07:58 +0200, Hans Dockter wrote:
>> On Jun 18, 2008, at 7:55 AM, Russel Winder wrote:
>>
>>> On Wed, 2008-06-18 at 07:30 +0200, Hans Dockter wrote:
>
>>>> Another cool tool would be generating cross source references for
>>>> Groovy like JXR (http://maven.apache.org/plugins/maven-jxr-plugin).
>>>
>>> Is there an Ant version of this?  Currently the Groovy build is Ant
>>> based so Maven plugins are not that useful.
>>
>> I don't know if there is an Ant Version. But you can use JXR directly
>> via Java/Groovy.
>
> That works for me :-)
>
> Though we must make sure it doesn't become a required jar for the  
> Groovy
> distribution.

Its nice to have JXR applied against the Groovy JAVA sources. My  
original proposal was writing a Groovy tool that generates this cross  
source references for Groovy code.

- Hans

>
> -- 
> Russel.
> ====================================================
> Dr Russel Winder                 Partner
>
> Concertant LLP                   t: +44 20 7585 2200, +44 20 7193 9203
> 41 Buckmaster Road,              f: +44 8700 516 084
> London SW11 1EN, UK.             m: +44 7770 465 077

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

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

    http://xircles.codehaus.org/manage_email
Permalink | Reply |

Gmane