commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jörg Schaible <Joerg.Schai...@scalaris.com>
Subject javadocs
Date Mon, 02 Dec 2013 09:07:59 GMT
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


Mime
View raw message