commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Henri Yandell <flame...@gmail.com>
Subject Re: javadocs
Date Thu, 05 Dec 2013 08:23:29 GMT
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 <garydgregory@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
> <Joerg.Schaible@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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message