On 18/10/2013 10: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],
...
Oops, missing link :-S
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
[4] https://jira.codehaus.org/browse/ENUNCIATE-429
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
