Hi, 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)
Regards, Andrei. > -----Original Message----- > From: Christian Schneider [mailto:[email protected]] On Behalf Of > Christian Schneider > Sent: Donnerstag, 3. April 2014 07:48 > To: [email protected] > 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 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
