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 <[EMAIL PROTECTED]>:
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 <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]>
