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