XPCOM Documentation tree

I got tired of all the meta-discussion about documentation and decided

to actually write some, starting with XPCOM... and I need your help. 
There's an outline with links here:

http://www.mozilla.org/projects/xpcom/doc/

The idea is that this guide is for clients of XPCOM - these are not the 
internal details of how this stuff works, but rather a set of "how to 
use XXX" style documents. The string guide and array guides are good 
examples. If you're getting this e-mail then I'm asking you to help out 
(see below) - at least getting us started.

I've tried to make this the comprehensive list of "what is in xpcom.dll" 
without covering too much obsolete stuff like nsFileSpec. I went through 
a list of every file in mozilla/xpcom (except the XPConnect stuff) and 
tried to figure out where that file would be documented.. and came up 
with the above list.

to get this kicked off, I've added some skeleton docs for what I believe 
to be the "hotspots" of documentation in XPCOM - the areas that are:
- well defined and thus easily documented
- well owned, and thus has a good expert
- the areas that people use the most and thus need the documentation 
desperately.

I've linked to these skeleton docs in the link above.
There are a few areas that I think we can start documenting now, and 
here's where I need your help:
- directory service (ccarlen)
- timers (pavlov)
- string escaping (darin)
- pipes (darin)
- streams (darin)
- proxies, threads (dougt)
- event queues (danm) (overlap with proxies/threads, obviously)
- nsIFile and friends (dougt)
- fastload (brendan)
- atoms (alecf)
- property lists (alecf)
- hashtables (alecf, bsmedberg, jkeiser)
- observers (alecf, dougt)

There are lots of other issues that we can dwell on like:
- these docs are in the wrong place on mozilla.org
- I don't like the style/organization/formatting
- this stuff isn't frozen
- I want to write my docs in TeX

all I ask is that *for now*, you table these issues. We can always move 
the docs, reformat them, freeze/obsolete interfaces, etc later.. but for 
now if you have the time, it would be great if you could just start 
filling in the docs themselves - the content is what is important here. 
If we get a more comprehensive mozilla.org doc story, we can always move 
the stuff you write into that system.

Also, I'm not married to this particular organization, it is just what 
made sense to me at the time. If you want to move/combine/split some of 
these subject areas, feel free - lets not discuss it too much lets just 
do it!

Alec

P.S. see http://www.mozilla.org/README-cvs.html for easy instructions to 
check out the files, or just:

cvs -d:pserver:email%[email protected]:/cvsroot co 
html/projects/xpcom/