No apologies necessary. It's my kneejerk view of the world for API... heh. Tend to forget the original :)
Owen Rubel 415-971-0976 oru...@gmail.com On Mon, Nov 9, 2015 at 9:00 AM, Dzmitry Kazimirchyk <dkazimirc...@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 >> oru...@gmail.com <mailto:oru...@gmail.com> >> >> On Mon, Nov 9, 2015 at 7:54 AM, Dzmitry Kazimirchyk >> <dkazimirc...@gmail.com <mailto:dkazimirc...@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 >> >> >>
