Hi Francesco,
On 21/10/13 07:58, Francesco Chicchiriccò wrote:
On 18/10/2013 19:06, Sergey Beryozkin wrote:
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;
+1
This would be a very nice add-on, IMHO.
I'm just hoping it may be the simplest way to do it because the
generator has all the context info in time it may decide to check for a
javadocs resource, ex, it will know that the current root resource or
even subresource method is a JAX-RS method after all, that no
@Description targeting specific method or parameters exist, so it might
be simpler;
The possible downside is that if it works then a generated JavaDocs jar
would need to be shipped;
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...
+1
Also this seems to be a nice option, actually even lighter for
end-users, I'd say.
Yes, no need to ship a javadocs jar and do any extra config, but I agree
with Dan, it is a bit more involved to implement :-), we'll see, may be
we'll end up supporting multiple options here.
Thanks for taking this seriously ;-)
Np, thanks for initiating this thread, I can't prioritize immediately on
this issue but hope we can make it work somehow soon enough...
Cheers, Sergey
Regards.
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
