#4 docstrings

[Garth T Kidd]

Self-evident:

* We need docstrings.

Not as self-evident:

* Since __version__ is a release version number,
updated manually, we can't put ``$Revision$``
in it. On the other hand, it *is* very handy
to be able to figure out which revision of the
parser you're using -- especially when you want
to submit a bug for it.

I propose using either or both of the following
in modules::

__revision__ = """$Revision$"""

__id__ = """$Id$"""

[David Goodger]

Logged In: YES
user_id=7733

I've come to the opinion that extra variables like
__revision__ are evil. Better to put them in the module
docstring, which I'll do.

[Garth T Kidd]

Logged In: YES
user_id=59803

Fair enough. So long as I can see it from pydoc.help()'s
output, I'm happy. :)

[David Goodger]

Logged In: YES
user_id=7733

Closing down this project soon (will resume under Docutils),
so closing this bug. Some docstrings have been added, but
there's room for plenty more.

The requirement for docstrings will be a permanent part of
the project's coding standard. As for the
__special_variables__, time will tell; that's a Python policy
decision, not reStructuredText syntax.