httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Re: Developer documentation
Date Wed, 01 Dec 2010 16:25:41 GMT

On Nov 28, 2010, at 9:38 AM, Stefan Fritsch wrote:

> 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''

I particularly like http://httpd.apache.org/dev/API.html which is the  
Shambhala API. Nice from a historical perspective, but makes us look  
like abandonware.

>>
>> 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.

Yes. It is. I didn't want to dump it wholesale into the docs before I  
figured out how to auto-update it.

I could use some help on this.

I think, unfortunately, that this falls squarely on the docs team to  
JFDI, although, granted, we need quite a bit of help for the twiddly  
bits. I would rather have nothing, or just the auto-gen docs, than  
have all this old and contradictory stuff as our only API documentation.

Additionally, there's a lot of outdated and Just Plain Wrong stuff on http://modules.apache.org/reference.php

  which is hosted elsewhere. That (modules.apache.org in general) has  
come up again and again, but nobody really has the time/passion to do  
much about it.

--
Rich Bowen
rbowen@rcbowen.com


Mime
View raw message