cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrei Shakirin <>
Subject RE: CXF javadoc questions for 3.0
Date Thu, 03 Apr 2014 08:36:55 GMT

For me javadocs will be reasonable for APIs staying stable between major releases.
Users can rely to use this in custom code.
Such classes are mostly located in cxf-api, my +1 to restrict distribution to cxf-api javadoc
(despite of fact that there are also some useful javadocs in cxf-core)


> -----Original Message-----
> From: Christian Schneider [] On Behalf Of
> Christian Schneider
> Sent: Donnerstag, 3. April 2014 07:48
> To:
> Subject: Re: CXF javadoc questions for 3.0
> 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 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
> Open Source Architect
> Talend Application Integration Division

View raw message