You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lenya.apache.org by "J. Wolfgang Kaltz" <ka...@interactivesystems.info> on 2005/03/17 11:15:49 UTC
api docs / lenya.apache.org
Dear devs
I have just updated the API docs and am wondering if we should simplify
the process.
First, I don't think the API docs should be versioned. The API docs are
generated from the classes, whereas the classes are already versioned -
so versioning the generated API docs provides no added value.
Furthermore there is a consistency problem: if a class is deleted from
the sources, its' API .html is still in the SVN. So someone would have
to think about removing that from SVN as well. Otherwise a class will
still show up in the Javadocs, even though it actually no longer exists.
Next problem: the Javadocs on the Website are typically out of date
anyway, since currently somebody has to think about locally generating
them, then copying them to his local lenya/site, then checking them in.
I see that on minotaur, there is a Javadoc installed. I also see that we
have direct access to the /www/lenya.apache.org directory, which is the
root of our homepage (http://lenya.apache.org)
So suggestion / food for thought:
- create a daily cron job on Minotaur which once a day generates the
Javadocs directly into /www/lenya.apache.org/apidocs (or some other
directory).
- remove the apidocs from svn
Advantages:
- online Javadocs would be up-to-date (within 24 hours)
- the overhead for checking them in disappears -> less work for the
community and less load for the server svn
WDYT ?
Wolfgang
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org
Re: api docs / lenya.apache.org
Posted by "Gregor J. Rothfuss" <gr...@apache.org>.
J. Wolfgang Kaltz wrote:
> either
> (1) Provide online API docs only for releases. When a new 1.2 is
> released, the release process will include updating the online API docs.
> For 1.4, there will only be online API docs once it is released. Devs
> working on 1.4 should generate their own docs (build.sh javadocs) to
> ensure they are looking at consistent docs. For now, apidocs/1.4 is
> removed from svn (and from the Website).
>
> (2) The online API docs reflect the source code that is checked in. This
> can only be guaranteed if they are generated automatically from the
> source code, on the server.
>
> Since policy seems to go against (2),
> here is my +1 for proposal (1)
i don't think the occasional out of date or incomplete reference
outweighs the comfort of having javadocs available online, especially
for people curious about lenya. i would therefore suggest to keep things
as is, update the javadocs at least once per release, and wait until
helios comes online, and we can have our vmware instance to run a
javadocs cronjob
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org
Re: api docs / lenya.apache.org
Posted by "J. Wolfgang Kaltz" <ka...@interactivesystems.info>.
Gregor J. Rothfuss schrieb:
>> (...)
>> Advantages:
>> - online Javadocs would be up-to-date (within 24 hours)
>> - the overhead for checking them in disappears -> less work for the
>> community and less load for the server svn
>
>
> would need to be discussed with infrastructure, but sounds interesting.
I understand the concerns regarding performance on infrastructure, but I
would like to point out that the API docs for 1.4 alone consist of
almost 800 items that need to be managed by subversion. A new local
Javadoc generation will overwrite those items, so doing a svn checkin on
these is quite some load for the subversion server, as I noticed
yesterday. (BTW the subversion server is the same as the Webserver
anyway). Plus, in order for the API docs to be up-to-date, this process
would need to be done on a regular basis.
This is in addition to the consistency problem mentioned yesterday
(online stuff typically not up to date, plus possible online API docs
for classes no longer existing). So IMO we should change something in
the current process,
either
(1) Provide online API docs only for releases. When a new 1.2 is
released, the release process will include updating the online API docs.
For 1.4, there will only be online API docs once it is released. Devs
working on 1.4 should generate their own docs (build.sh javadocs) to
ensure they are looking at consistent docs. For now, apidocs/1.4 is
removed from svn (and from the Website).
(2) The online API docs reflect the source code that is checked in. This
can only be guaranteed if they are generated automatically from the
source code, on the server.
Since policy seems to go against (2),
here is my +1 for proposal (1)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org
Re: api docs / lenya.apache.org
Posted by "Gregor J. Rothfuss" <gr...@apache.org>.
J. Wolfgang Kaltz wrote:
> Dear devs
>
> I have just updated the API docs and am wondering if we should simplify
> the process.
>
> First, I don't think the API docs should be versioned. The API docs are
> generated from the classes, whereas the classes are already versioned -
> so versioning the generated API docs provides no added value.
everything that goes onto the site has to be in svn. this allows
infrastructure to restore the site easily in case of disaster.
> Furthermore there is a consistency problem: if a class is deleted from
> the sources, its' API .html is still in the SVN. So someone would have
> to think about removing that from SVN as well. Otherwise a class will
> still show up in the Javadocs, even though it actually no longer exists.
> Next problem: the Javadocs on the Website are typically out of date
> anyway, since currently somebody has to think about locally generating
> them, then copying them to his local lenya/site, then checking them in.
>
> I see that on minotaur, there is a Javadoc installed. I also see that we
> have direct access to the /www/lenya.apache.org directory, which is the
> root of our homepage (http://lenya.apache.org)
>
> So suggestion / food for thought:
> - create a daily cron job on Minotaur which once a day generates the
> Javadocs directly into /www/lenya.apache.org/apidocs (or some other
> directory).
> - remove the apidocs from svn
>
> Advantages:
> - online Javadocs would be up-to-date (within 24 hours)
> - the overhead for checking them in disappears -> less work for the
> community and less load for the server svn
would need to be discussed with infrastructure, but sounds interesting.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org