You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cxf.apache.org by Daniel Kulp <dk...@apache.org> on 2014/04/02 20:38:56 UTC
CXF javadoc questions for 3.0
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?
--
Daniel Kulp
dkulp@apache.org - http://dankulp.com/blog
Talend Community Coder - http://coders.talend.com
Re: CXF javadoc questions for 3.0
Posted by Andrew <dr...@gmail.com>.
Hi Dan,
I think creating the distibution for javadocs is a very right thing. What do you think about going further
and providing it as yet another CXF downloadable (like sources for example)? So the main distribution will
stay small but people may download the javadocs as well if they will. My assumption is that most of the
people google javadocs online.
Best Regards,
Andriy Redko
DK> For 2.x, we basically generated 2 different sets of Javadoc for 2 different purposes:
DK> 1) We generated the javadoc ONLY for the cxf-api. This is the javadoc that we stuck in the “docs” dir of the distribution.
DK> 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.
DK> There are some problems with both…. cxf-api misses a ton of stuff that we expect users to use. Things like the
DK> HttpConduits for configuring http settings, lots of JAX-RS things, the JAX-WS factories, etc…. The second one
DK> 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.
DK> For 3.0, we want to get rid of the big bundle. Thus, generating 2 needed a re-think. I just pushed some changes
DK> to create a distribution/javadoc module to handle that. It now includes EVERYTHING other than the wars and tests.
DK> Thus, it really is a complete javadoc of everything in CXF.
DK> Now, the question comes: what do we want to include and where? The full javadoc is 168MB. Do we want to include
DK> that in the distribution? (although it compresses very very well so doesn’t balloon the tar.gz/zip up by much). Or
DK> do we want to include only some subset for the distribution? Just “cxf-core” to match what we included for 2.x?
DK> More? Alternatively, in the docs dir, just put a simple read me that points to cxf.apache.org/docs for the main
DK> docs and the appropriate javadoc dir for javadoc? That may be the most appropriate since we don’t include any
DK> “real” docs in the distribution anyway, just the javadocs.
DK> Thoughts?
RE: CXF javadoc questions for 3.0
Posted by Andrei Shakirin <as...@talend.com>.
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:cschneider111@gmail.com] On Behalf Of
> Christian Schneider
> Sent: Donnerstag, 3. April 2014 07:48
> To: dev@cxf.apache.org
> 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
Re: CXF javadoc questions for 3.0
Posted by Christian Schneider <ch...@die-schneider.net>.
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
Re: CXF javadoc questions for 3.0
Posted by Jason Pell <ja...@pellcorp.com>.
I would think hosting javadocs only online would make most sense.
On 03/04/2014 5:39 AM, "Daniel Kulp" <dk...@apache.org> wrote:
>
> 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?
>
> --
> Daniel Kulp
> dkulp@apache.org - http://dankulp.com/blog
> Talend Community Coder - http://coders.talend.com
>
>
Re: CXF javadoc questions for 3.0
Posted by Daniel Kulp <dk...@apache.org>.
I made a few changes to the javadoc stuff. If LDAP ever comes back, I’ll get it committed.
Basically, for the distribution, I’ll leave the javadoc at just the “core” javadoc. However, it also generates a jar of the full javadoc for everything. This is what will be deployed to the website.
Since it’s an artifact, it will also be available in the maven repo. For example, what I committed yesterday is at:
https://repository.apache.org/content/repositories/snapshots/org/apache/cxf/cxf-javadoc/3.0.0-SNAPSHOT/
(I’m changing the group-id to cxf-distribution-javadoc once I can commit). Thus, we could easily add links to download the full thing if wanted to.
The latest 3.0.0-SNAPSHOT javadocs are now on the website: http://cxf.apache.org/javadoc/latest-3.0.x/
Dan
On Apr 2, 2014, at 2:38 PM, Daniel Kulp <dk...@apache.org> wrote:
>
> 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?
>
> --
> Daniel Kulp
> dkulp@apache.org - http://dankulp.com/blog
> Talend Community Coder - http://coders.talend.com
>
--
Daniel Kulp
dkulp@apache.org - http://dankulp.com/blog
Talend Community Coder - http://coders.talend.com