Hi All,
I wonder if we can try and add a property to WadlGenerator, such as
"checkJavaDocs" or may be "javaDocsClassPath" which will point to a
generated java docs jar, then suppose it processes a root class like
mypackage.Root, then it will look for
/mypackage/Root.html Java Doc resource, load it and try to scrape HTML
(it seemed to be a proper XML) for the info. I've no idea if it will
work but I might give it a try;
I also like the idea of auto-generating Descriptions with ASM, I'd try
to explore it further if the above will prove to be too messy and
unrealistic...
Thanks, Sergey
On 18/10/13 09:59, Francesco Chicchiriccò wrote:
On 15/10/2013 17:32, Daniel Kulp wrote:
Interesting…. We haven't really looked at anything javadoc related as
that information isn't available at runtime. It's only available at
build time and thus we'd need special tools and such to parse the
javadoc at build time, output a file or something that can be picked
up later.
Jersey has a javadoc doclet that will output a special XML file that
the runtime can be configured to augment the stuff that the runtime
produces. We could likely use the exact same XML file so we don't
need to produce our own doclet. That said, that does require that
the maven javadoc plugin be configured to ALWAYS run as part of your
build. That does slow the builds down a little bit.
Another option COULD be a "doclet" that would use ASM or something to
actually update the compiled .class files with @Description
annotations. Definitely more involved and likely wouldn't work as
well in an IDE though.
I've been trying Enunciate in these days, for documentation only [3],
via its maven plugin.
While generating <doc> elements from Javadocs was working fine (I guess
with an approach similar to what reported above), I have found some
other serious issues: no support for base types (xs:int, xs:string, ...
are just ignored), no support for JAXB collections [4], ...
I gave up with Enunciate then - even though their HTML output looks
quite nice - and came back to "pure" CXF WADL generation: I am now
working on something to generate some HTML from WADL via XSLT.
Regards.
On Oct 15, 2013, at 8:53 AM, Francesco Chicchiriccò
<[email protected]> wrote:
Hi all,
by reading [1], I am currently annotating JAX-RS methods (for
WADL-generation) like this
/**
* Deletes the user matching the provided userId.
*
* @param userId id of user to be deleted
* @return Deleted user
*/
@DELETE
@Path("{userId}")
@Descriptions({
@Description(target = DocTarget.METHOD, value = "Deletes the
user matching the provided userId"),
@Description(target = DocTarget.RETURN, value = "Deleted user")
})
UserTO delete(@PathParam("userId") Long userId);
As you can see, there is an evident duplication here, so I was
thinking if Javadoc elements might be used for WADL documentation and
found [2] for Jersey.
Is there anything similar planned for CXF?
TIA
Regards.
[1]
http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL
[2]
https://wikis.oracle.com/display/Jersey/SupportedJavadocTagsForExtendedWADL
[3] http://docs.codehaus.org/display/ENUNCIATE/Documentation+Only
--
Sergey Beryozkin
Talend Community Coders
http://coders.talend.com/
Blog: http://sberyozkin.blogspot.com
