apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ge...@lobstertechnology.com
Subject re: Documentation
Date Sat, 31 Dec 2005 11:44:46 GMT

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 <gerry@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 <inoue@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 <inoue@ariel-networks.com>
>>
>
>




Mime
View raw message