Hi Martin,
I got just far enough in reading the Jersey code to understand where I
would actually start coding to get this to work, but then all chances
to work on this got sucked dry.
I still fully intend to do it--I know that doesn't help you much but
there it is.
Seth
On Tue, Jun 3, 2008 at 4:21 AM, Martin Grotzke
<martin.grotzke_at_freiheit.com> wrote:
> Hi Seth,
>
> do you already have some results?
>
> Cheers,
> Martin
>
>
> On Wed, 2008-04-30 at 06:47 -0500, Seth Call wrote:
>> Alright. I'll prototype it and poke my head back up when I get
>> something working.
>>
>> Thanks for the guidance,
>> Seth
>>
>> On Wed, Apr 30, 2008 at 6:29 AM, Marc Hadley <Marc.Hadley_at_sun.com> wrote:
>> > On Apr 29, 2008, at 10:56 PM, Seth Call wrote:
>> >
>> >
>> > > Let me propose an alternate solution... see what you all think:
>> > >
>> > > Say instead that something like the previously attached
>> > > javadoc-containing XML file was deployed with a Jersey instance. Say
>> > > it always lives in a known 'resource' directory of some sort.
>> > >
>> > > The current dynamic WADL generating code could be altered to look for
>> > > the presence of this XML resource file; if it finds it, it could XPath
>> > > into it to extract out the relevant Javadoc bits for
>> > > resources/requests etc.
>> > >
>> > > I like this because there remains one way to get your WADL, and this
>> > > feature is clearly more incremental in nature.
>> > >
>> > > Anyone else favor this as much as I do? This sounds ideal to me, but
>> > > admittedly I don't have the big picture here.
>> > >
>> > >
>> > That sounds like a good approach to me. I had in mind something similar
>> > using a pre-built WADL directly rather than an intermediate XML format but
>> > either works I think.
>> >
>> > Marc.
>> >
>> >
>> >
>> >
>> > >
>> > > On Tue, Apr 29, 2008 at 9:09 PM, Seth Call <sethcall_at_gmail.com> wrote:
>> > >
>> > > > Using the Bookstore Jersey 0.7 example as source to test on, the XML
>> > > > doclet I wrote generates the attached XML (just so an example can be
>> > > > seen).
>> > > >
>> > > > In short, it's all the javadoc data, along with
>> > > > class/method/interface/annotation information. I believe a WADL
>> > > > could be generated directly from this XML, using just XSLT.
>> > > >
>> > > > But I was hoping to get just a little bit of guidance, because making
>> > > > a new doclet (instead of using this existing XML doclet w/ XSLT) would
>> > > > allow one to *feasibly* reuse code within jersey that does the dynamic
>> > > > WADL generation, so that one could make changes to WADL generation
>> > > > code in one place and have it take affect in both the dynamic piece
>> > > > and the doclet piece. The question is such a common factoring
>> > > > realistic.
>> > > >
>> > > > So, I tried to find the code that does the dynamic generation, and I
>> > > > believe the bulk of it is in:
>> > > >
>> > > > jersey/src/impl/com/sun/ws/rest/impl/WadlGenerator.java
>> > > >
>> > > > From what I can tell, it would be very hard to somehow use this code
>> > > > within the context of a doclet, since it seems quite tied to running
>> > > > within the context of the jersey runtime. Does anyone else have a gut
>> > > > feel on this?
>> > > >
>> > > > I'm still interested in trying to generate the WADL from a doclet, and
>> > > > I believe I will start doing just that. So if anyone thinks it's
>> > > > wrong to use the XML Doclet /XSLT, then let me know. Otherwise I'll
>> > > > take a serious stab at it and ping back here when I make progress.
>> > > >
>> > > > Regards,
>> > > > Seth
>> > > >
>> > > >
>> > > >
>> > > > On Tue, Apr 29, 2008 at 10:46 AM, Seth Call <sethcall_at_gmail.com> wrote:
>> > > >
>> > > > > Hi Marc,
>> > > > >
>> > > > > I see. I had in mind that there would be a new annotation (or param
>> > > > > on existing annotations) that let you document these elements, but I
>> > > > > can appreciate that Javadoc would be
>> > > > >
>> > > > > 1) more intuitive/less learning curve
>> > > > > 2) more readable compared to an inline string.
>> > > > >
>> > > > > Funny thing is, I just open-sourced a doclet that generates an XML
>> > > > > representation of the data in Javadoc on google code. I'm thinking one
>> > > > > could use XSLT/XPATH on the output of this doclet, and create the WADL
>> > > > > from it. Are there any red flags with using this XML-generating,
>> > > > > maven-based, Apache 2.0 licensed project hosted on google code to help
>> > > > > accomplish this? Or would there be a reason that this must be a new
>> > > > > doclet sourced directly with Jersey?
>> > > > >
>> > > > > I don't have a good feel for the size of this task, but I am very
>> > > > > interested. I'd like to look through the Jersey source a little
>> > > > > tonight to get a better feel...
>> > > > >
>> > > > > Thanks,
>> > > > > Seth
>> > > > >
>> > > > >
>> > > > >
>> > > > > On Tue, Apr 29, 2008 at 10:18 AM, Marc Hadley <Marc.Hadley_at_sun.com>
>> > wrote:
>> > > > >
>> > > > > > This is one of those tasks that we've discussed but haven't had the
>> > time to
>> > > > > > implement yet. We discussed implementing a doclet that would
>> > generate a WADL
>> > > > > > from the Javadoc in resource classes. One issue with this is that
>> > this would
>> > > > > > require a compile-time step rather than the current all-runtime WADL
>> > support
>> > > > > > but I think that it would be possible to allow the runtime
>> > /application.wadl
>> > > > > > to be overridden with a pre-generated file that contains
>> > documentation.
>> > > > > >
>> > > > > > Any volunteers to help with creating such a doclet ?
>> > > > > >
>> > > > > > Marc.
>> > > > > >
>> > > > > >
>> > > > > >
>> > > > > > On Apr 29, 2008, at 11:04 AM, Seth Call wrote:
>> > > > > >
>> > > > > >
>> > > > > > >
>> > > > > > >
>> > > > > > >
>> > > > > > >
>> > > > > > > I'm trying out Jersey and something stands out... I don't see a
>> > way
>> > > > > > > that someone can cause text to emit into the WADL 'doc' element,
>> > which
>> > > > > > > is available on most elements in WADL (such as request, resource,
>> > > > > > > resources, etc).
>> > > > > > >
>> > > > > > > Am I missing something?
>> > > > > > >
>> > > > > > > I think the value here is obvious, but I'll state it anyway just
>> > in case:
>> > > > > > >
>> > > > > > > Giving a way to allow developers to document the individual
>> > elements
>> > > > > > > of an interface, in the structure that those elements occur,
>> > greatly
>> > > > > > > lowers the bar for creating documentation. Javadoc is probably
>> > the
>> > > > > > > best example.
>> > > > > > > Specific to Jersey and WADLs, one can then easily process the XML
>> > > > > > > using XSLT or XPATH and generate quality documentation.
>> > > > > > >
>> > > > > > > The 'doc' element can be seen in the WADL specification:
>> > > > > > > https://wadl.dev.java.net/wadl20061109.pdf. p21-29 for RelaxNG
>> > or
>> > > > > > > XSD definitions.
>> > > > > > >
>> > > > > > > So anyway, if there isn't a way to do this today, is the next step
>> > for
>> > > > > > > me to open an enhancement request in the tracker?
>> > > > > > >
>> > > > > > > Seth
>> > > > > > >
>> > > > > > >
>> > ---------------------------------------------------------------------
>> > > > > > > To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> > > > > > > For additional commands, e-mail: users-help_at_jersey.dev.java.net
>> > > > > > >
>> > > > > > >
>> > > > > > >
>> > > > > >
>> > > > > > ---
>> > > > > > Marc Hadley <marc.hadley at sun.com>
>> > > > > > CTO Office, Sun Microsystems.
>> > > > > >
>> > > > > >
>> > > > > >
>> > > > > >
>> > ---------------------------------------------------------------------
>> > > > > > To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> > > > > > For additional commands, e-mail: users-help_at_jersey.dev.java.net
>> > > > > >
>> > > > > >
>> > > > > >
>> > > > >
>> > > > >
>> > > > >
>> > > > > --
>> > > > > The poor have to labour in the face of the majestic equality of the
>> > > > > law, which forbids the rich as well as the poor to sleep under
>> > > > > bridges, to beg in the streets, and to steal bread.
>> > > > >
>> > > > >
>> > > >
>> > > >
>> > >
>> > > ---------------------------------------------------------------------
>> > > To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> > > For additional commands, e-mail: users-help_at_jersey.dev.java.net
>> > >
>> > >
>> >
>> > ---
>> > Marc Hadley <marc.hadley at sun.com>
>> > CTO Office, Sun Microsystems.
>> >
>> >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
>> > For additional commands, e-mail: users-help_at_jersey.dev.java.net
>> >
>> >
>>
>>
>
>