I created an issue awhile back to get something like
@Path(value="/", doc="the path")
supported for all of the JAX-RS annotations.
The idea is to come up with a single well known property that the future code or service api info generation tools can use.
For example, some use JavaDocs - which overloads it a bit because what is documented at the Java level and what is visible to the HTTP service consumer may not always make sense to keep in sync.
Then we have Swagger2 annotations related to the docs, in CXF we also have @Description annotations that can be used by the WADL filter.
Having a 'doc' would be a simple improvement which can help to minimize the 'noise' related to everyone using their own annotations/approaches to documenting JAX-RS API...