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.