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