httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Error code documentation
Date Mon, 12 Mar 2012 16:01:04 GMT
Please consider this just a first-draft brainstorm, dumped directly from IRC discussion, and
not thoroughly thought through. I'm looking for suggestions that make the least amount of
work for everyone. And of course I, along with various other people on the docs@ list, are
volunteering to do the bootstrap work here.

Having error codes is a huge benefit to our users, and we would like to avoid creating unnecessary
work in maintaining the docs for them going forward. The real value is in the how-to-fix-this
documentation that would accompany more complex error conditions.

There's been some discussion over on docs@ about the best way to tackle the error code documentation.
It's a bit of a daunting task, and we want 
to be sure that it gets done in a way that is sustainable going forward.

Solutions that have been suggested are:



* A foo_errors.xml file that accompanies any source code foo.c file that contains one or more
APLOGNO's

Might look something like
<error>
<logno>00653</logno>
<message>Something bad happened</message>
<description>More details go here</description>
<url>http://more.info/</url>
<module>mod_rewrite</module>
</error>

Advantages: Easy to parse. File is right there when you're editing the source. Easier to maintain
than one gargantuan errors document. Easy to update by non-programming documentation folks
who can just open the xml file and augment the description and URL after the other basics
have been provided. Easy to auto-generate the basics from the source. Easy to translate (foo_errors.xml.fr,
foo_errors.xml.de).
Disadvantages: Dozens of additional files laying about in the source tree. Can put them elsewhere,
but that reduces the chances that someone will think to edit it when they edit the source.



* Doxygen-style comments in the code. Docs regenerated from this when changed.

Advantages: Right there in the source when you need it. Easy to parse
Disadvantages: Harder to do multiple languages. More intimidating for non-programmer types
to get in there and update descriptions. Lots of additional prose in the source code.


* We maintain everything over in the docs tree, either in one gargantuan file, or in smaller
files that in some way reflect the structure of the source tree.

Advantages: Docs are where they belong, rather than cluttering the source tree.
Disadvantage: Out of sight, out of mind. Error descriptions don't get updated when new errors
are added.



--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org







Mime
View raw message