Hi Seth,
I'm going to have a first version ready next week, perhaps you can have
a look at it then if it fits your needs.
Cheers,
Martin
On Wed, 2008-06-11 at 09:49 -0500, Seth Call wrote:
> 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
> >> >
> >> >
> >>
> >>
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net