Hi Lars,
On Tue, 2008-06-10 at 15:39 +0200, Lars Tackmann wrote:
> On Tue, Jun 10, 2008 at 10:06 AM, Martin Grotzke
> <martin.grotzke_at_freiheit.com> wrote:
> > Hi,
> >
> > I want to improve the generation of wadl so that resource and method
> > comments are added to the related wadl-elements.
>
> Yes please - regarding how the comments are wirtten, am I then the
> only one who prefer a annotation style similar to the one used in
> testng i.e:
>
> --
> @Test(description = "should assert that resource exists")
> --
>
> in JAX-RS this could be something like the following:
>
> --
> @Path("/users", description = "handle user interaction")
> public class UserResource {
> @POST(description = "create new user")
> public Response createUser(User user) {
> :
> }
>
> @GET(description = "get all users")
> public List<User> getUsers() {
> :
> }
> }
> --
>
> I know this requires API changes and does not allow for reuse of
> JavaDoc comments, but most of the time I am much more verbose in my
> JavaDoc comments anyway and also this has the benefit of being usable
> in the auto generation of the WADL file.
I also thought about creating custom annotations for this, but finally
thought that it would be good to separate functionality and
documentation. That's why I prefer to keep documentation in javadoc,
also as then we have much more flexibility for describing things like
params, return types, methods, resources and stuff via custom taglets.
>
> Anyway any technique that will allow comments in the wadl is greatly
> welcome, even if I have to run a seperate program to create them.
I plan to realize this via a maven plugin, so that it can be fully
integrated into the build process and the created information can be
used both via invoking the plugin directly (and getting the generated
wadl) and by requesting the application.wadl at runtime.
> By
> the way it would be nice if with support for subresources in the wadl
> documentation:
>
> --
> @Path("/users/config)
> public ConfigResource getConfigResource() {
> return new ConfigResource();
> }
> --
I totally agree, I just try to solve this, hopefully Paul can help with
this.
>
> I have found that users (the programmers that uses my REST services)
> have a hard time understanding that a single wadl document might not
> be the entire picture. If such subresources was picket up by the
> document generator then the user could browse it from there.
Yes, that's one reason why we wrote our wadl completely by hand until
now.
Cheers,
Martin