Why do we need javadoc at all? If we create source jars for every maven
artifact and a source distribution we should already provide all
informations necessary.
At least when using an IDE the user will automatically see the javadoc
generated from the source.
So the only difference is for users who do not use an IDE. At least for
me the only case where I sometimes hit javadoc is when searching on the
web. I never downloaded javadoc and used it.
Christian
Am 02.04.2014 20:38, schrieb Daniel Kulp:
For 2.x, we basically generated 2 different sets of Javadoc for 2 different
purposes:
1) We generated the javadoc ONLY for the cxf-api. This is the javadoc that we
stuck in the “docs” dir of the distribution.
2) As part of the big cxf-bundle build, we generated javadocs for everything
that went in the bundle. This is what we deployed to the website.
There are some problems with both…. cxf-api misses a ton of stuff that we
expect users to use. Things like the HttpConduits for configuring http
settings, lots of JAX-RS things, the JAX-WS factories, etc…. The second one
includes a lot more stuff, but still misses anything in the services (sts,
ws-discovery, etc…). Plus, those are just available on-line. Not sure if
that’s an issue.
For 3.0, we want to get rid of the big bundle. Thus, generating 2 needed a
re-think. I just pushed some changes to create a distribution/javadoc module
to handle that. It now includes EVERYTHING other than the wars and tests.
Thus, it really is a complete javadoc of everything in CXF.
Now, the question comes: what do we want to include and where? The full
javadoc is 168MB. Do we want to include that in the distribution? (although
it compresses very very well so doesn’t balloon the tar.gz/zip up by much). Or
do we want to include only some subset for the distribution? Just “cxf-core”
to match what we included for 2.x? More? Alternatively, in the docs dir,
just put a simple read me that points to cxf.apache.org/docs for the main docs
and the appropriate javadoc dir for javadoc? That may be the most appropriate
since we don’t include any “real” docs in the distribution anyway, just the
javadocs.
Thoughts?
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
