You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@httpd.apache.org by Igor Galić <i....@brainsware.org> on 2010/11/28 03:32:30 UTC
Developer documentation
Hi folks,
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 ;)
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, 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.
</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).
So long,
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Developer documentation
Posted by Rich Bowen <rb...@rcbowen.com>.
On Dec 7, 2010, at 6:02 AM, Igor Galić wrote:
> 05:54 < gmcdonald> jMCg: http://ci.apache.org/projects/httpd/trunk/doxygen/
> 06:21 < infrabot> Gavin Closed: (INFRA-3252) Please add a nightly
> doxygen build for httpd trunk
>
> Now all we need to do is link to it.
> If it turns out we like it even more than just that, we should have
> it published
> directly to site.
Done
------------------------------------------------------------------------
r1042988 | rbowen | 2010-12-07 06:57:36 -0500 (Tue, 07 Dec 2010) | 2
lines
Changed paths:
M /httpd/httpd/trunk/docs/manual/developer/index.html.en
M /httpd/httpd/trunk/docs/manual/developer/index.xml
Use the developer docs on ASF hardware, instead of rcbowen.com
------------------------------------------------------------------------
Thanks, Gav.
--
Rich Bowen
rbowen@rcbowen.com
Re: Developer documentation
Posted by Igor Galić <i....@brainsware.org>.
----- "Igor Galić" <i....@brainsware.org> wrote:
> > >> 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'll ask Gav from infra to the rescue.
05:54 < gmcdonald> jMCg: http://ci.apache.org/projects/httpd/trunk/doxygen/
06:21 < infrabot> Gavin Closed: (INFRA-3252) Please add a nightly doxygen build for httpd trunk
Now all we need to do is link to it.
If it turns out we like it even more than just that, we should have it published
directly to site.
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Developer documentation
Posted by Igor Galić <i....@brainsware.org>.
> >> 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'll ask Gav from infra to the rescue.
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Developer documentation
Posted by Rich Bowen <rb...@rcbowen.com>.
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
Re: Developer documentation
Posted by Stefan Fritsch <sf...@sfritsch.de>.
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
Re: Developer documentation
Posted by Rich Bowen <rb...@rcbowen.com>.
On Dec 1, 2010, at 11:24 AM, Igor Galić wrote:
>
> <snip>
>> The first topic discusses is ``Apache *1.3* API Notes''
>
> http://modules.apache.org/doc/API.html
> http://httpd.apache.org/docs/trunk/developer/API.html
> http://httpd.apache.org/dev/API.html
>
> All reference the same document, and from what Rich told me
> that's *pre* 1.3...
Yep. Shambhala is what became 1.0
--
Rich Bowen
rbowen@rcbowen.com
Re: Developer documentation
Posted by Igor Galić <i....@brainsware.org>.
<snip>
> The first topic discusses is ``Apache *1.3* API Notes''
http://modules.apache.org/doc/API.html
http://httpd.apache.org/docs/trunk/developer/API.html
http://httpd.apache.org/dev/API.html
All reference the same document, and from what Rich told me
that's *pre* 1.3...
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/