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
