[
https://issues.apache.org/jira/browse/WINK-372?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13498528#comment-13498528
]
Etienne Canaud commented on WINK-372:
-------------------------------------
Good pick on backward compatibility.
One option is to keep the "value" element for the Doc title, and add an
optional "content" element:
{code:title=WADLDoc.java|borderStyle=solid}
public @interface WADLDoc {
String value();
String content() default "";
}
{code}
Pros: Backward compatible with @WADLDoc("...") and @WADLDoc(value="...").
Cons: If both title and content are specified, the title has to be defined with
the "value" element name, which is not very intuitive when reading code:
@WADLDoc(value = "some title", content = "some content")
Any proposal for a better solution?
> Support for WADL Doc text content when using @WADLDoc annotation in Resource
> class
> ----------------------------------------------------------------------------------
>
> Key: WINK-372
> URL: https://issues.apache.org/jira/browse/WINK-372
> Project: Wink
> Issue Type: Improvement
> Components: Server
> Affects Versions: 1.1.2, 1.1.3, 1.2
> Reporter: Etienne Canaud
> Priority: Trivial
>
> Support for WADL was added in Wink 1.1.2 in Wink #313
> (https://issues.apache.org/jira/browse/WINK-313).
> It is stated that "You can document your resources, params, and request
> entities with @ WADLDoc to add some description."
> However, after some tests and a quick peek at the source code, it seems that
> the @ WADLDoc annotation only takes one string parameter (value), and this
> string will end up in the "title" of the WADL Doc element, while the content
> of the Doc will remain empty and can't be assigned using annotations.
> You can refer to line 768 of WADLGenerator.java, where there is no sign of
> the Doc content being set:
> {code:title= WADLGenerator.java|borderStyle=solid}
> Doc getDocument(WADLDoc desc) {
> Doc d = new Doc();
> d.setTitle(desc.value());
> return d;
> }
> {code}
> This improvement could be implemented in (at least) two different ways:
> 1) Add one element to WADLDoc annotation (i.e. instead of only value(), have
> title() and content()).
> 2) Rename WADLDoc annotation to WADLDocTitle and create a new WADLDocContent
> annotation, each having a single value() element. Both annotations would be
> used to create the Doc object when generating WADL.
> Doc content is supposed to be mixed content (i.e. it can hold some
> sub-elements) and my improvement request is only a half-baked implementation
> where only text content would be supported.
> I could eventually work on a patch once the implementation details are
> specified if this improvement gets approved - still, changes should be pretty
> straightforward.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
