cxf-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sergey Beryozkin (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (CXF-5353) WADLGenerator needs to support existing JavaDocs when possible
Date Thu, 02 Jan 2014 16:20:51 GMT

    [ 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)

Mime
View raw message