You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@groovy.apache.org by Dzmitry Kazimirchyk <dk...@gmail.com> on 2015/11/09 16:54:13 UTC
Groovydoc and java code
Hi,
We are trying to build API documentation for a mixed source java/groovy
project. We see groovydoc tool from standard groovy distribution as a
good fit for our needs since it supports doc generation from both java
and groovy sources and also allows us to use groovy templates which is
very useful for building our heavily customized docs.
However we hit a few obstacles related to the ability of groovydoc to
handle java sources:
1. It fails to parse files containing Java 8 specific syntax;
2. It also fails to parse files containing Java 7 "diamond" operator;
3. Javadocs for individual enum constants from java classes don't make
it into final GroovyClassDoc metadata and hence into the docs (this
works fine for groovy sources though).
We can mostly live with not having Java 8 syntax support for now, and
work around Java 7 diamond issue, but having docs for enum constants is
absolutely vital.
In general I wonder if we are on a right track here using groovydoc. Is
it supposed to handle java (mixed java/groovy) sources? If so whether
support for Java 7 and 8 syntax is coming soon?
Also should I create issue in JIRA regarding the java enum docs problem?
I have tried to wrap my head around the parser logic and found that it
uses old ANTLR v2 grammar. So I wonder if it is even worth looking into
trying to figure out and fix this ourselves or there are plans on moving
to ANTLR v3 or some other parser tool in the near future?
Thanks for your help,
Dima
Re: Groovydoc and java code
Posted by Owen Rubel <or...@gmail.com>.
No apologies necessary. It's my kneejerk view of the world for API... heh.
Tend to forget the original :)
Owen Rubel
415-971-0976
orubel@gmail.com
On Mon, Nov 9, 2015 at 9:00 AM, Dzmitry Kazimirchyk <dk...@gmail.com>
wrote:
> Hi Owen,
>
> Thanks for your reply. My apologies, I should have mentioned that by API I
> mean API documentation for java/groovy classes, like the one at
> http://docs.groovy-lang.org/latest/html/gapi/
>
> Sorry for this confusion.
>
>
> Dima
>
> On 11/09/2015 06:07 PM, Owen Rubel wrote:
>
>> I've talked about this alot. The easiest way to do this is through
>> OPTIONS.
>>
>> Implement the request.method OPTIONS for all endpoints so each endpoint
>> can send back its information. Then at runtime, you can cache this
>> information and show it per AUTHORITY/ROLE in your apidocs view.
>>
>> I've already implemented this in the old Grails API Toolkit; you can
>> download and look at the source code I believe.
>>
>>
>> Owen Rubel
>> 415-971-0976
>> orubel@gmail.com <ma...@gmail.com>
>>
>> On Mon, Nov 9, 2015 at 7:54 AM, Dzmitry Kazimirchyk
>> <dkazimirchyk@gmail.com <ma...@gmail.com>> wrote:
>>
>> Hi,
>>
>> We are trying to build API documentation for a mixed source
>> java/groovy project. We see groovydoc tool from standard groovy
>> distribution as a good fit for our needs since it supports doc
>> generation from both java and groovy sources and also allows us to
>> use groovy templates which is very useful for building our heavily
>> customized docs.
>>
>> However we hit a few obstacles related to the ability of groovydoc
>> to handle java sources:
>>
>> 1. It fails to parse files containing Java 8 specific syntax;
>> 2. It also fails to parse files containing Java 7 "diamond" operator;
>> 3. Javadocs for individual enum constants from java classes don't
>> make it into final GroovyClassDoc metadata and hence into the docs
>> (this works fine for groovy sources though).
>>
>> We can mostly live with not having Java 8 syntax support for now,
>> and work around Java 7 diamond issue, but having docs for enum
>> constants is absolutely vital.
>>
>> In general I wonder if we are on a right track here using groovydoc.
>> Is it supposed to handle java (mixed java/groovy) sources? If so
>> whether support for Java 7 and 8 syntax is coming soon?
>>
>> Also should I create issue in JIRA regarding the java enum docs
>> problem?
>>
>> I have tried to wrap my head around the parser logic and found that
>> it uses old ANTLR v2 grammar. So I wonder if it is even worth
>> looking into trying to figure out and fix this ourselves or there
>> are plans on moving to ANTLR v3 or some other parser tool in the
>> near future?
>>
>>
>> Thanks for your help,
>> Dima
>>
>>
>>
Re: Groovydoc and java code
Posted by Dzmitry Kazimirchyk <dk...@gmail.com>.
Hi Owen,
Thanks for your reply. My apologies, I should have mentioned that by API
I mean API documentation for java/groovy classes, like the one at
http://docs.groovy-lang.org/latest/html/gapi/
Sorry for this confusion.
Dima
On 11/09/2015 06:07 PM, Owen Rubel wrote:
> I've talked about this alot. The easiest way to do this is through OPTIONS.
>
> Implement the request.method OPTIONS for all endpoints so each endpoint
> can send back its information. Then at runtime, you can cache this
> information and show it per AUTHORITY/ROLE in your apidocs view.
>
> I've already implemented this in the old Grails API Toolkit; you can
> download and look at the source code I believe.
>
>
> Owen Rubel
> 415-971-0976
> orubel@gmail.com <ma...@gmail.com>
>
> On Mon, Nov 9, 2015 at 7:54 AM, Dzmitry Kazimirchyk
> <dkazimirchyk@gmail.com <ma...@gmail.com>> wrote:
>
> Hi,
>
> We are trying to build API documentation for a mixed source
> java/groovy project. We see groovydoc tool from standard groovy
> distribution as a good fit for our needs since it supports doc
> generation from both java and groovy sources and also allows us to
> use groovy templates which is very useful for building our heavily
> customized docs.
>
> However we hit a few obstacles related to the ability of groovydoc
> to handle java sources:
>
> 1. It fails to parse files containing Java 8 specific syntax;
> 2. It also fails to parse files containing Java 7 "diamond" operator;
> 3. Javadocs for individual enum constants from java classes don't
> make it into final GroovyClassDoc metadata and hence into the docs
> (this works fine for groovy sources though).
>
> We can mostly live with not having Java 8 syntax support for now,
> and work around Java 7 diamond issue, but having docs for enum
> constants is absolutely vital.
>
> In general I wonder if we are on a right track here using groovydoc.
> Is it supposed to handle java (mixed java/groovy) sources? If so
> whether support for Java 7 and 8 syntax is coming soon?
>
> Also should I create issue in JIRA regarding the java enum docs problem?
>
> I have tried to wrap my head around the parser logic and found that
> it uses old ANTLR v2 grammar. So I wonder if it is even worth
> looking into trying to figure out and fix this ourselves or there
> are plans on moving to ANTLR v3 or some other parser tool in the
> near future?
>
>
> Thanks for your help,
> Dima
>
>
Re: Groovydoc and java code
Posted by Owen Rubel <or...@gmail.com>.
I've talked about this alot. The easiest way to do this is through OPTIONS.
Implement the request.method OPTIONS for all endpoints so each endpoint can
send back its information. Then at runtime, you can cache this information
and show it per AUTHORITY/ROLE in your apidocs view.
I've already implemented this in the old Grails API Toolkit; you can
download and look at the source code I believe.
Owen Rubel
415-971-0976
orubel@gmail.com
On Mon, Nov 9, 2015 at 7:54 AM, Dzmitry Kazimirchyk <dk...@gmail.com>
wrote:
> Hi,
>
> We are trying to build API documentation for a mixed source java/groovy
> project. We see groovydoc tool from standard groovy distribution as a good
> fit for our needs since it supports doc generation from both java and
> groovy sources and also allows us to use groovy templates which is very
> useful for building our heavily customized docs.
>
> However we hit a few obstacles related to the ability of groovydoc to
> handle java sources:
>
> 1. It fails to parse files containing Java 8 specific syntax;
> 2. It also fails to parse files containing Java 7 "diamond" operator;
> 3. Javadocs for individual enum constants from java classes don't make it
> into final GroovyClassDoc metadata and hence into the docs (this works fine
> for groovy sources though).
>
> We can mostly live with not having Java 8 syntax support for now, and work
> around Java 7 diamond issue, but having docs for enum constants is
> absolutely vital.
>
> In general I wonder if we are on a right track here using groovydoc. Is it
> supposed to handle java (mixed java/groovy) sources? If so whether support
> for Java 7 and 8 syntax is coming soon?
>
> Also should I create issue in JIRA regarding the java enum docs problem?
>
> I have tried to wrap my head around the parser logic and found that it
> uses old ANTLR v2 grammar. So I wonder if it is even worth looking into
> trying to figure out and fix this ourselves or there are plans on moving to
> ANTLR v3 or some other parser tool in the near future?
>
>
> Thanks for your help,
> Dima
>
Re: Groovydoc and java code
Posted by ari <ar...@ish.com.au>.
I note that some older requests for groovydoc help have also gone unanswered
here: http://www.groovy-lang.org/mailing-lists.html#nabble-td5716399
I wonder if the old Antlr parser no longer has any Groovy devs maintaining
it (it takes a special kind of person to read and understand it). And given
this activity on the javaparser mailing list to encourage them to the Apache
license: https://github.com/javaparser/javaparser/issues/144 I'm guessing
there is some interest in replacing at least part of the parser with
something modern and supported.
That's glaforge who appears to be driving that. Is that still the case
within Groovy devs?
Cheers
Ari
--
View this message in context: http://groovy.329449.n5.nabble.com/Groovydoc-and-java-code-tp5729284p5729339.html
Sent from the Groovy Users mailing list archive at Nabble.com.