groovy-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Owen Rubel <oru...@gmail.com>
Subject Re: Groovydoc and java code
Date Mon, 09 Nov 2015 17:06:12 GMT
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 <dkazimirchyk@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 <mailto:orubel@gmail.com>
>>
>> On Mon, Nov 9, 2015 at 7:54 AM, Dzmitry Kazimirchyk
>> <dkazimirchyk@gmail.com <mailto:dkazimirchyk@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
>>
>>
>>

Mime
View raw message