FroMage
Class level comments not shown in the description table
Reported by [email protected], Jul 19, 2011 What steps will reproduce the problem? 1.Add some comment to the class level such as:
/**
- description */ @Path("/mypath") @Produces(MediaType.APPLICATION_JSON) public class MyClass { ... }
What is the expected output? What do you see instead? In the resources table containing /mypath there is no information in the description column
What version of the product are you using? On what operating system? v0.9.0 - WinXP/Linux
Please provide any additional information below. Please indicate the proper way to add comments at that level.
comment Comment 1 by project member stephane.epardaud, Jul 20, 2011 We don't do anything with the class javadoc because it doesn't represent any resource. Methods represent resources, so that's what we use. Classes are only logical agregations of resources that don't have any correlation with resource locations.
What should we do for instance in this case?
@Path("foo") class A { @GET public String get(); }
@Path("foo") class B { @POST public void post(); }
We chose to only use method-level javadoc because those are always meaningful. If you can convince me otherwise, I will change it, but so far I haven't found a good reason to change that behaviour.
comment Comment 2 by [email protected], Jul 20, 2011 The idea to use comments is not to all classes but for the ones which are adding @Path annotation. So imagine that you have:
/**
- Contains all services for the customer */ @Path("/customer") Class Customer{
/**
- register a new customer */ @POST @Path("/register") public void register(...)
/**
- Return */ @GET @Path("/information") public CustomerVO information(@QueryParam("customerId") customerId) }
It would be great having the class level javadoc in the documentation so you can see that all services under path /customer are meant to be used for all customer services, etc.
However, I see your point regarding the problem having same path in different classes. Maybe the first or the last description can be added to the table? Currently there is simply no information displayed in the table containing paths w/o being methods
comment Comment 3 by project member stephane.epardaud, Jul 20, 2011 Ah, I see what you mean, we could use the class javadoc for @Path("customer") if there is no jax-rs resource method for this url, but still you wouldn't see it in the documentation page for the sub-resources (information, register).
comment Comment 4 by [email protected], Jul 20, 2011 I've seen you don't have that case in your example: http://www.lunatech-labs.com/files/jax-doclets/jaxrsdocs/index.html
But I have one path which I have no access (@GET, @POST...), so it's a way to group my services logically in a path. Then I can access to that level in the documentation and I see all the subpath available with empty description.
Try to create a similar case just to see what you get (i.e Resource table w/o Method table).
This is nothing critical, but for the way we're using rest would be ok.
BTW, nice doclet, it's been really useful :)
comment Comment 5 by project member stephane.epardaud, Jul 20, 2011 Yes I understand what you mean, if I do this change you will get the doc for the /customer path, but you won't see that doc for /customer/information for example, since technically /customer is a parent resource.
