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
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
