re: Documentation

[ge...@lobstertechnology.com]

I've been thinking about APR docs in the background for a few weeks 
since the brief list thread (that I'm replying against).  I've had some 
thoughts...

I've written some stuff using PHP in the past, and quite like the way 
they present their documentation:

   http://www.php.net/manual/en/
   http://www.php.net/manual/en/ref.filesystem.php

They provide a good level of detail in describing each function and 
package, and ontop of this they allow developers using it to contribute 
a "note" against the methods which generally contain example code, 
discussions of memory and CPU useage and other stuff.

I think this idea can be re-applied to the APR documentation.  It's a 
fairly embryonic idea at the moment, but I thought I'd kick it out 
there and get a bit of feedback before diving-in.


DoxyGen can output XML, so we could write some scripts/apps to 
manipulate the XML document.  This would allow us, for example, to:

1) Import each function/packages descriptions into a MySQL database.

2) Build a DB table of user submitted notes/comments

3) Produce a PHP app that can then present this to the user


There are some considerations/assumptions
a) APR doesn't have a huge load so a DB hit isn't such a big deal for 
each page request, though if neccessary we could regenerate static 
content from the DB on each update.

b) The web host has, or can be configured with, a DB.

c) The web host has, or can be configured with, a web-scripting 
language like PHP/Perl/Java

d) All functions would need to have a "since" attribute (javadoc: 
@since) so we can denote, when presenting to the user, what versions 
support the function.   [Does doxygen supprt "since"? hmm]

e) We'd need some way (manual/automagic) to handle changes like:
   i)   function name
   ii)  function prototype
   iii) function deprecation
In PHP docs they have one big-document that covers all versions of 
their API and each function is annotated with supporting versions etc.  
To follow this model would perhaps be difficult at this time, given 
some of the discussions I've read about potentially removing the 
dependency on memory pooling in APR and other potentially major re-work.

f) We could use a Wiki instead/as-well.

Discuss?

Cheers
Gerry Calderhead

Quoting Gerry <ge...@everythingsucks.co.uk>:

> It surprises me that there appears to be no consolidated effort from 
> APR do this
> under the FDL or some other open documentation license.
>
> INOUE's documents are the most comprehensive I've seen (having based 
> my own code
> on lessons from Nick Kew's tutorials and the Apache2/APR code 
> itself), I wonder
> what else exists?
>
> Have there been moves previously to build a consolidated open set of APR
> documents as part of the core project?
>
> Is there an appetite for this?
>
> G
>
> INOUE Seiichiro <in...@ariel-networks.com> wrote:
>
>> > On Thu, Nov 24, 2005 at 01:13:03PM +0000, Gerry wrote:
>> > > Is anyone actively working on documenting APR ?
>> > > I can see nothing about any such activity on the website.
>> > >
>> > There's an external tutorial at http://dev.ariel-networks.com/apr/
>>
>> Thanks for reference.
>> I maintain the tutorial.
>>
>> I hope we can work on something together.
>>
>> - INOUE Seiichiro <in...@ariel-networks.com>
>>
>
>

Re: Documentation

[Paul Querna <ch...@force-elite.com>]

gerry@lobstertechnology.com wrote:
> 
> I've been thinking about APR docs in the background for a few weeks 
> since the brief list thread (that I'm replying against).  I've had some 
> thoughts...
> 
> I've written some stuff using PHP in the past, and quite like the way 
> they present their documentation:
> 
>   http://www.php.net/manual/en/
>   http://www.php.net/manual/en/ref.filesystem.php
> 
> They provide a good level of detail in describing each function and 
> package, and ontop of this they allow developers using it to contribute 
> a "note" against the methods which generally contain example code, 
> discussions of memory and CPU useage and other stuff.
> 
> I think this idea can be re-applied to the APR documentation.  It's a 
> fairly embryonic idea at the moment, but I thought I'd kick it out there 
> and get a bit of feedback before diving-in.
> 
> 
> DoxyGen can output XML, so we could write some scripts/apps to 
> manipulate the XML document.  This would allow us, for example, to:
> 
> 1) Import each function/packages descriptions into a MySQL database.
> 
> 2) Build a DB table of user submitted notes/comments
> 
> 3) Produce a PHP app that can then present this to the user
> 
> 
> There are some considerations/assumptions
> a) APR doesn't have a huge load so a DB hit isn't such a big deal for 
> each page request, though if neccessary we could regenerate static 
> content from the DB on each update.
> 
> b) The web host has, or can be configured with, a DB.

The web host must be easily moved between servers.  Our current servers 
do not run a database for any TLP site.

> c) The web host has, or can be configured with, a web-scripting language 
> like PHP/Perl/Java

The web host cannot run anything besides CGI.  We only use a CGI for the 
download page.  I don't think we want to expand the use of CGI, for the 
sake of the load average of minotaur and ajax.

Our website should be purely static files.  This is currently a 
requirement(1) for almost all the TLPs and their websites.

I think better documentation is a good thing.  I don't want to stand in 
the way of that.  I am not sure I like the PHP method of allowing 
comments.  I believe documentation should be authoritative, not 'maybe 
this will work, but try this other way someone mentioned in the comments'.

(1) Okay, so its not written in stone anywhere, but I think there would 
be major resistance to running PHP on the main apache.org webserver(s). 
  Maybe we will have more options once FastCGI support is in 
mod_proxy... but not right now.

-Paul