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
http://sberyozkin.blogspot.com
Talend Community Coders
http://coders.talend.com/
