Marc, I completely vote for annotations. I have already set up such a system for my project (@WadlDoc, @WadlIgnore, @WadlReturn, and some other home-brew annotations...) and do JAXBElement QName deduction. Works like a charm! The home-brew annotations (eg a wiki link) could probably be turned into something more general.
/Isak
> From: Marc Hadley <marc.hadley_at_oracle.com>
> Content-Type: text/plain; charset=us-ascii
> Date: Mon, 12 Apr 2010 11:56:23 -0400
> Subject: Enhanced WADL Generation Thoughts
>
> The current extended WADL support is based on custom Javadoc tags:
>
> http://wikis.sun.com/display/Jersey/WADL
>
> Its very handy but it suffers from a couple of problems:
>
> (i) Its quite involved to set up
> (ii) Its not very internationalization (I18N) friendly.
>
> The current support can be split into two functional areas:
>
> (a) Additional runtime information
> (b) Documentation
>
> It seems to me that for (a) we could fix (i) by making the following
> Javadoc tags (see
> http://wikis.sun.com/display/Jersey/SupportedJavadocTagsForExtendedWADL
> ) be annotations instead:
>
> @request.representation.qname
> @request.representation.mediaType
> @response.param
> @response.representation.XXX.qname
> @response.representation.XXX.mediaType
>
> E.g. to provide additional metadata about a set of possible responses
> produced by a method you could add the following annotation:
>
> @WadlResponses({
> @WadlResponse(status=200, mediaType="application/foo+xml",
> entity=Foo.class),
> @WadlResponse(status=400, mediaType="application/error+xml",
> name="error", namespace="http//example.com/errors")
> })
>
> As an aside it looks like one can determine the QName of a JAXB
> annotated class at runtime so the first @WadlResponse should be
> implementable.
>
> Using annotations for this would remove the need for addition steps in
> the build and greatly simplify things IMO.
>
> For (b) I really like the re-use of Javadoc but looking at the I18N
> tools out there it seems like most (if not all) are based on property
> files in resource bundles. We could address (ii) by supporting property
> files that hold the additional documentation. We could define some kind
> of method->property name mapping so that alternate localizations can be
> included with an app and selected at runtime using the value of the
> HTTP Accept-Language header. I think this would also address (i) since
> the property files can easily be included when building the code but it
> would lose the connection to Javadoc unless we offered some doclet that
> would generate the initial property files from existing javadoc.
>
> What do folks think ?
>
> Thanks,
> Marc.
>
>
>
>