WC-NG - Doc strings and API design

We need doc strings. We always do, but especially at this point we need
them in order to assist other people in joining the effort to implement
WC-NG. I think one of the most useful things I can do at this point is
help write them.

Doc strings go hand in hand with API design, as I'm sure we all know
(subconsciously at least), so as I try to write them I am necessarily
examining and trying to guess and then sometimes suggesting changes to
the API design. Sometimes that will be a separate step, sometimes part
of the same patch.

Most of the APIs I'm looking at are private and sparsely documented, and
'wc_db.h' has a comment ending, '... do not want to doc until it feels
like it is "Right"'. It seems the time is now Right to consolidate,
document, and change where better options are now apparent. I don't
want to step on anyone's toes or make gratuitous changes, so let me know
if I seem to be doing so.

And I'm not going to do the whole API on my own. I'll do some parts.
Please step in and fix up another part of it if you can.
  
- Julian
Received on 2010-03-01 14:02:38 CET