Hello Paul,
Is the issue specified below, which was raised in the past being taken
into account while Enhancing WADL generation ?
https://jersey.dev.java.net/issues/show_bug.cgi?id=416
Can we add support for inferring method return types, from the method
declarations instead of adding this information through Java DOC
Could you please let me know,
Thanks,
Suchitha
-----Original Message-----
From: Paul.Sandoz_at_Sun.COM [mailto:Paul.Sandoz_at_Sun.COM]
Sent: Tuesday, April 13, 2010 7:37 AM
To: users_at_jersey.dev.java.net
Subject: Re: [Jersey] Enhanced WADL Generation Thoughts
On Apr 12, 2010, at 5:56 PM, Marc Hadley wrote:
> 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.
>
Agreed on both points. It works and it can work well once set up but i
think it is a good time to review and improve it.
It is also specific to JavaDoc so we would require something separate
say to work with ScalaDoc.
> 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.
>
A minor suggestion: should we make the annotations, by name,
independent of WADL?
> 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 ?
>
Looks like a good proposal to me.
Paul.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
For additional commands, e-mail: users-help_at_jersey.dev.java.net