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