You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Jörg Schaible <Jo...@scalaris.com> on 2013/12/02 10:07:59 UTC
javadocs
Hi folks,
it seems we have currently a great diversity with the provided javadocs of
our components. Some provide the latest one from trunk only, some provide
also a link the the latest one released and some have links to the
individual releases. However, after updating some links in our Maven
projects to support links to the Apache Common classes from our own
javadocs, it is obvious that most of the components I tried to update,
simply fail in some way:
1/ beanutils
- http://commons.apache.org/proper/commons-beanutils/javadocs/v_1.8.x/apidocs with x in [0-3], link for 1.8.3 in main
menu still refers
http://commons.apache.org/beanutils/javadocs/v1.8.3/apidocs/, but a redirect
is in place
- there is no link to the current API in trunk, nor a unified link to the
latest release
2/ cli
- http://commons.apache.org/proper/commons-cli/javadocs/api-1.x with x in
[0-2]
- http://commons.apache.org/proper/commons-cli/javadocs/api-release (same
content as version 1.2)
- http://commons.apache.org/proper/commons-cli/apidocs contains trunk
3/ codec
- http://commons.apache.org/proper/commons-codec/javadocs/api-1.7 only
- http://commons.apache.org/proper/commons-codec/javadocs/api-release is 1.7
instead of latest release 1.8, even main menu refers 1.7
- http://commons.apache.org/proper/commons-codec/apidocs contains trunk
4/ configuration
- http://commons.apache.org/proper/commons-configuration/javadocs/apidocs_1.x with x in [0-6], links for [7-10] are
missing
- http://commons.apache.org/proper/commons-configuration/apidocs provides
latest release ... other components will provide javadocs of trunk with this
link
- there is no link to the current API in trunk
5/ email
- http://commons.apache.org/proper/commons-email/javadocs/api-x with x in
[1.2,1.3], 1.3.1 and 1.3.2 missing
- http://commons.apache.org/proper/commons-email/javadocs/api-release
contains 1.3.2
- http://commons.apache.org/proper/commons-email/apidocs contains trunk
6/ logging
- http://commons.apache.org/proper/commons-logging/javadocs/api-x with x in
[1.0.4,1.1,1.1.2]
- http://commons.apache.org/proper/commons-logging/javadocs/api-release
contains 1.1.2
- http://commons.apache.org/proper/commons-logging/apidocs contains trunk
I did not check any other component, but it seems that the preferred schema
is the one of cli or logging. IMHO it is preferable to link to the latest
release with a "constant" link as well as with a link containing the
version. While there is no explicit requirement to unify the link schema
between all components, it is bad if the standards are different concerning
the links in the main menu of the components or the link schema is suddenly
discontinued (missing links to older versions, links used for trunk suddenly
used for the release or - worst case - not providing a link to the latest
release at all).
One main problem is that the site of a component at time of voting is never
"final". I stopped to report problems with such links, because it was always
claimed, that the links will be fine, once the site is published. Obviously
not true.
Cheers,
Jörg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: javadocs
Posted by Henri Yandell <fl...@gmail.com>.
Here's an old thought - but why not centralize the javadoc?
Instead of having components managing their release javadoc, instead make a
central library in which the javadoc sites, then deep link to a components
item within it. Then it's pretty easy to find an old release, pull the
javadoc out and plop them in SVN/file location.
Hen
On Mon, Dec 2, 2013 at 6:18 AM, Gary Gregory <ga...@gmail.com> wrote:
> It sounds like we should:
>
> - Define a guideline for components to layout Javadoc
> - Make it easy for component to implement, how? Right now it's another
> manual step in an already lengthy and error prone release process. Ugh.
>
> Gary
>
>
> On Mon, Dec 2, 2013 at 4:07 AM, Jörg Schaible
> <Jo...@scalaris.com>wrote:
>
> > Hi folks,
> >
> > it seems we have currently a great diversity with the provided javadocs
> of
> > our components. Some provide the latest one from trunk only, some provide
> > also a link the the latest one released and some have links to the
> > individual releases. However, after updating some links in our Maven
> > projects to support links to the Apache Common classes from our own
> > javadocs, it is obvious that most of the components I tried to update,
> > simply fail in some way:
> >
> > 1/ beanutils
> >
> > -
> >
> http://commons.apache.org/proper/commons-beanutils/javadocs/v_1.8.x/apidocswithx in [0-3], link for 1.8.3 in main
> > menu still refers
> > http://commons.apache.org/beanutils/javadocs/v1.8.3/apidocs/, but a
> > redirect
> > is in place
> > - there is no link to the current API in trunk, nor a unified link to the
> > latest release
> >
> > 2/ cli
> >
> > - http://commons.apache.org/proper/commons-cli/javadocs/api-1.x with x
> in
> > [0-2]
> > - http://commons.apache.org/proper/commons-cli/javadocs/api-release(same
> > content as version 1.2)
> > - http://commons.apache.org/proper/commons-cli/apidocs contains trunk
> >
> > 3/ codec
> >
> > - http://commons.apache.org/proper/commons-codec/javadocs/api-1.7 only
> > - http://commons.apache.org/proper/commons-codec/javadocs/api-release is
> > 1.7
> > instead of latest release 1.8, even main menu refers 1.7
> > - http://commons.apache.org/proper/commons-codec/apidocs contains trunk
> >
> > 4/ configuration
> >
> > -
> >
> http://commons.apache.org/proper/commons-configuration/javadocs/apidocs_1.xwithx in [0-6], links for [7-10] are
> > missing
> > - http://commons.apache.org/proper/commons-configuration/apidocsprovides
> > latest release ... other components will provide javadocs of trunk with
> > this
> > link
> > - there is no link to the current API in trunk
> >
> > 5/ email
> >
> > - http://commons.apache.org/proper/commons-email/javadocs/api-x with x
> in
> > [1.2,1.3], 1.3.1 and 1.3.2 missing
> > - http://commons.apache.org/proper/commons-email/javadocs/api-release
> > contains 1.3.2
> > - http://commons.apache.org/proper/commons-email/apidocs contains trunk
> >
> > 6/ logging
> >
> > - http://commons.apache.org/proper/commons-logging/javadocs/api-x with x
> > in
> > [1.0.4,1.1,1.1.2]
> > - http://commons.apache.org/proper/commons-logging/javadocs/api-release
> > contains 1.1.2
> > - http://commons.apache.org/proper/commons-logging/apidocs contains
> trunk
> >
> >
> > I did not check any other component, but it seems that the preferred
> schema
> > is the one of cli or logging. IMHO it is preferable to link to the latest
> > release with a "constant" link as well as with a link containing the
> > version. While there is no explicit requirement to unify the link schema
> > between all components, it is bad if the standards are different
> concerning
> > the links in the main menu of the components or the link schema is
> suddenly
> > discontinued (missing links to older versions, links used for trunk
> > suddenly
> > used for the release or - worst case - not providing a link to the latest
> > release at all).
> >
> > One main problem is that the site of a component at time of voting is
> never
> > "final". I stopped to report problems with such links, because it was
> > always
> > claimed, that the links will be fine, once the site is published.
> Obviously
> > not true.
> >
> > Cheers,
> > Jörg
> >
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
>
> --
> E-Mail: garydgregory@gmail.com | ggregory@apache.org
> Java Persistence with Hibernate, Second Edition<
> http://www.manning.com/bauer3/>
> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
> Spring Batch in Action <http://www.manning.com/templier/>
> Blog: http://garygregory.wordpress.com
> Home: http://garygregory.com/
> Tweet! http://twitter.com/GaryGregory
>
Re: javadocs
Posted by Gary Gregory <ga...@gmail.com>.
It sounds like we should:
- Define a guideline for components to layout Javadoc
- Make it easy for component to implement, how? Right now it's another
manual step in an already lengthy and error prone release process. Ugh.
Gary
On Mon, Dec 2, 2013 at 4:07 AM, Jörg Schaible
<Jo...@scalaris.com>wrote:
> Hi folks,
>
> it seems we have currently a great diversity with the provided javadocs of
> our components. Some provide the latest one from trunk only, some provide
> also a link the the latest one released and some have links to the
> individual releases. However, after updating some links in our Maven
> projects to support links to the Apache Common classes from our own
> javadocs, it is obvious that most of the components I tried to update,
> simply fail in some way:
>
> 1/ beanutils
>
> -
> http://commons.apache.org/proper/commons-beanutils/javadocs/v_1.8.x/apidocswith x in [0-3], link for 1.8.3 in main
> menu still refers
> http://commons.apache.org/beanutils/javadocs/v1.8.3/apidocs/, but a
> redirect
> is in place
> - there is no link to the current API in trunk, nor a unified link to the
> latest release
>
> 2/ cli
>
> - http://commons.apache.org/proper/commons-cli/javadocs/api-1.x with x in
> [0-2]
> - http://commons.apache.org/proper/commons-cli/javadocs/api-release (same
> content as version 1.2)
> - http://commons.apache.org/proper/commons-cli/apidocs contains trunk
>
> 3/ codec
>
> - http://commons.apache.org/proper/commons-codec/javadocs/api-1.7 only
> - http://commons.apache.org/proper/commons-codec/javadocs/api-release is
> 1.7
> instead of latest release 1.8, even main menu refers 1.7
> - http://commons.apache.org/proper/commons-codec/apidocs contains trunk
>
> 4/ configuration
>
> -
> http://commons.apache.org/proper/commons-configuration/javadocs/apidocs_1.xwith x in [0-6], links for [7-10] are
> missing
> - http://commons.apache.org/proper/commons-configuration/apidocs provides
> latest release ... other components will provide javadocs of trunk with
> this
> link
> - there is no link to the current API in trunk
>
> 5/ email
>
> - http://commons.apache.org/proper/commons-email/javadocs/api-x with x in
> [1.2,1.3], 1.3.1 and 1.3.2 missing
> - http://commons.apache.org/proper/commons-email/javadocs/api-release
> contains 1.3.2
> - http://commons.apache.org/proper/commons-email/apidocs contains trunk
>
> 6/ logging
>
> - http://commons.apache.org/proper/commons-logging/javadocs/api-x with x
> in
> [1.0.4,1.1,1.1.2]
> - http://commons.apache.org/proper/commons-logging/javadocs/api-release
> contains 1.1.2
> - http://commons.apache.org/proper/commons-logging/apidocs contains trunk
>
>
> I did not check any other component, but it seems that the preferred schema
> is the one of cli or logging. IMHO it is preferable to link to the latest
> release with a "constant" link as well as with a link containing the
> version. While there is no explicit requirement to unify the link schema
> between all components, it is bad if the standards are different concerning
> the links in the main menu of the components or the link schema is suddenly
> discontinued (missing links to older versions, links used for trunk
> suddenly
> used for the release or - worst case - not providing a link to the latest
> release at all).
>
> One main problem is that the site of a component at time of voting is never
> "final". I stopped to report problems with such links, because it was
> always
> claimed, that the links will be fine, once the site is published. Obviously
> not true.
>
> Cheers,
> Jörg
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/>
JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
Spring Batch in Action <http://www.manning.com/templier/>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory