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