httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefan Fritsch ...@sfritsch.de>
Subject Re: Developer documentation
Date Sun, 28 Nov 2010 14:38:55 GMT
On Sun, 28 Nov 2010, Igor Galić wrote:
> There's a PR, over three years old now:
> https://issues.apache.org/bugzilla/show_bug.cgi?id=42000
>
> complaining about the accuracy of the debugging documentation.
> Taking a look at it, I found that s/POOL_DEBUG/APR_POOL_DEBUG/
> is an easy fix, but as far as the rest goes, this is near
> impossible for your run-of-the-mill docs@ contributor.
>
> Looking further, I found a number of disharmonics.
> The only place ALLOC_DEBUG is referenced is in test/
> Most of the stuff in there hasn't been touched since a
> license header update 2006. What is test/?
>
> http://httpd.apache.org/docs/*trunk*/developer/
> Welcomes us to
> ``Developer Documentation for Apache *2.0*''
>
> The first topic discusses is ``Apache *1.3* API Notes''
>
> Rich has linked the autogenerated doxygen reference
> on his server as external resource. That's cool -
> but would probably make a better picture if it was hosted
> on httpd.a.o ;)

It would especially make a better picture if there was a cron job that 
kept the docs up-to-date. Rich's page is somewhat out of date by now.

> Trafficserver has it's doxygen generated by buildbot:
> http://ci.apache.org/builders/doxygen-nightly/
>
> And then we have:
> http://httpd.apache.org/dev/

This page should link to http://httpd.apache.org/docs/trunk/developer/ and 
the trunk API doc (once we have that on httpd.apache.org).

> This, sadly, doesn't even reference the above documentation.
> Instead we here have the original writeup of the 1.3 API,
> which seems the most complete reference on how the damn
> thing works^Hed we have.

There is also 
http://www.fmc-modeling.org/category/projects/apache/amp/Apache_Modeling_Project.html 
which is also out of date, but it is at least for 2.0. The interesting 
parts are in chapter 3 and 4, e.g. 
http://www.fmc-modeling.org/category/projects/apache/amp/3_3Extending_Apache.html 
This may be more useful to a httpd newbie than the 1.3 docs.

>
> </rant>
>
> Generally speaking: I'd like to see more of the external
> stuff internally, and have the internal stuff reference
> 2.3+ instead of 1.3.
>
> For starters: A friendly word in Infra's direction should
> get us the doxygen docs built nightly and published via
> SvnPubSub (wherever convenient).

That would be great.

Cheers,
Stefan

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