[
https://issues.apache.org/jira/browse/CXF-5353?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13860293#comment-13860293
]
Sergey Beryozkin commented on CXF-5353:
---------------------------------------
Hi Francesco, thanks for making it easy to debug :-)
After doing few more changes (and removing Description(s) from UserService) I
was able to see JavaDocs statements making it into the generated WADL, with the
only exception:
the statements containing the custom tags such as "tt" are ignored (I think
they'd have to be ignored even for a Maven plugin approach) because if they
make it into XML then they'd have to be escaped and stripping the unknown tags
from the texts is not guaranteed to produce the readable text in the end.
I think if one would like to have JavaDocs with the tags to present Java Api
nicely in HTML, then it may be reasonable to duplicate it with Description.
Otherwise one would likely see a 'representation conflict' where Java API docs
may be misrepresented as part of WADL. Realisitically the approach of scraping
the JavaDocs will work for 'plain' JavaDoc statements.
I think it is obvious the scraping approach is not perfect :-), and as such we
will also offer a Maven plugin, but I'm not sure it would let us handle complex
JavaDocs statements with the cross links/custom tags. Maven plugin will offer a
more robust approach toward dealing with the JavaDocs statements though I'm
also keen to maintain this scraping approach with should do for cases where the
generated JavaDocs are shipped.
Give it a try please.
Re duplicate schemas: it is a strange one, but the schemas are not identical,
they do have the same target namespace though, I'm not sure why JAXB compiler
makes such a decision, Dan do you know by any chance ?
FYI, I'm off tomorrow and next week
Thanks, Sergey
> WADLGenerator needs to support existing JavaDocs when possible
> --------------------------------------------------------------
>
> Key: CXF-5353
> URL: https://issues.apache.org/jira/browse/CXF-5353
> Project: CXF
> Issue Type: Improvement
> Reporter: Sergey Beryozkin
> Attachments: Syncope-trunk-CXF-5353.patch
>
>
> CXF @Description annotations targeting a given resource method (method itself
> and its in and response parameters) will often duplicate what the existing
> JavaDocs have already documented.
> WADLGenerator needs to do the best effort in trying to incorporate JavaDocs
> into the generated document.
--
This message was sent by Atlassian JIRA
(v6.1.5#6160)
