Mailing List Archive

rbb@covalent.net wrote:
>
> I wanted to give a potential project to anybody on this list looking for
> something to help with. :-) I would do this myself, but I have very
> poor HTML skills, and my documentation skills aren't great either. :-)
>
> Earlier this year, I spent a long time documenting the entire 2.0
> API. This has been done using ScanDoc, which is a tool to extract docs
> from C files. Basically, in all of the header files, we have comment
> blocks that look like:
>
> /**
> * ...
> */
>
> These are ScanDoc blocks. They way ScanDoc works is that there is a
> template perl script, that is filled out to actually generate the HTML
> files. It would be really cool if we could make the template file a bit
> cleaner or if it was modified to use DocBook instead of HTML.
>
> If anybody is interested in working on this with me, please let me know.

Indeed, I would be glad to take this on. Although it sounds like a large
task, and I am sure that we could spread the pain around.

Rich

> > These are ScanDoc blocks. They way ScanDoc works is that there is a
> > template perl script, that is filled out to actually generate the HTML
> > files. It would be really cool if we could make the template file a bit
> > cleaner or if it was modified to use DocBook instead of HTML.
> >
> > If anybody is interested in working on this with me, please let me know.
>
> Indeed, I would be glad to take this on. Although it sounds like a large
> task, and I am sure that we could spread the pain around.

Great. I agree, spreading the pain is a good idea. Here are my
thoughts. First of all, the really painful stuff is done, that would be
actually writing all of the docs. The only header file not documented is
buff.h, that is because I hope to remove BUFFs from Apache 2.0 in time.

There are a couple other things that are needed, and they can be done in
any order and mostly in parallel.

1) actually review the docs I wrote. The easiest way to do that, is
download the source tree from CVS, run ./buildconf and then 'make docs'
This should make all of the doc files. The docs are minimal, and having
somebody with better writing skills, and better HTML skills would be
wonderful.

2) Try to convert the template file to DocBook. The template is a perl
script that actually writes the docs to separate files. I am going to try
to figure out DocBook asap, and then I will try to convert the template
file. as soon as I start the template, I will commit a beginning to the
tree.

That's all I can think of, but I'm sure there is a lot more to do. If
somebody else wants to tackle the template file, please feel free. I'm
unlikely to get to it anytime soon.

Ryan

_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------

rbb@covalent.net wrote:
>
> First of all, the really painful stuff is done, that would be
> actually writing all of the docs.

I'm not sure I agree with this assessment. To me, documenting
a routine consists of much, much more than just baldly stating
what it does. API documentation should be more in-depth, and
include examples of usage, for instance. At least a paragraph,
not just a single line.

> The only header file not documented is buff.h, that is because
> I hope to remove BUFFs from Apache 2.0 in time.

Also not completely true. httpd.h has *lots* of undocumented
functions.

Just so anyone getting involved doesn't get surprised by
how much remains to be done.. A lot has already been
accomplished, but it's still only a start.
--
#ken P-)}

Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>