It was a bug which has now been fixed, for the moment you can just use a
parameter-level @Description:
public Response configure(@Description(...) MultipartBody multipart) { ... }
These parameter-level @Descriptions will always override the one
included in @Descriptions, thus you can do
@Descriptions({@Description(..., DocTarget.PARAM)})
public Response configure(@Description(...) @PathParam("id") long id,
MultipartBody multipart) { ... }
though perhaps param-level Descriptions should always be used when
describing indiv parameters
Sergey
On 28/11/11 10:31, Sergey Beryozkin wrote:
Hi Benson
I like the style, the subject was funny :-)
On 27/11/11 22:30, Benson Margulies wrote:
@Descriptions({
@Description(value = "Accepts the configuration of the service
as a set of multipart fields.", target = DocTarget.METHOD),
@Description(value = "Nothing, or an error message", target =
DocTarget.RETURN),
@Description(value = "btRoot: the location of the bt root
dirtectory", target = DocTarget.PARAM),
@Description(value = "btArch: for multi-architecture bt root
directories, the current architecture", target = DocTarget.PARAM),
@Description(value = "license: The XML License content",
target = DocTarget.PARAM),
})
public Response configure(MultipartBody multipart) { ... }
none of the PARAMs make it into the WADL. Should I just write a very
long string for REQUEST?
@Description with a DocTarget.PARAM applies to individual method
parameters, those which will make it as wadl:param elements, for
example, those annotated with @PathParam/@QueryParam; it only makes
sense embedding it inside @Descriptions when a single method parameter
annotated with @PathParam/@QueryParam exists. I'll need to update the
documentation for DocTarget.PARAM to make it less confusing.
In this case, please indeed write a long string for DocTarget.REQUEST,
right now WADL does not say much about describing complex multipart
payloads;
I think I should actually introduce a DocTarget.REPRESENTATION which
will be more precise.
How does RESPONSE differ from RETURN?
<response>
<!-- DocTarget.RESPONSE docs go here -->
<representation element="myns:Book">
<!-- DocTarget.RETURN docs go here -->
</representation>
</response>
Cheers, Sergey
--
Sergey Beryozkin
Talend Community Coders
http://coders.talend.com/
Blog: http://sberyozkin.blogspot.com
