How does pydoc parse code?

[Greg Kuperberg]

I plan to use pydoc for my Python project.  After looking through the
standard documentation, I am not sure how pydoc interprets its input.
In its basic operation it evidently looks at the first string literal in
the module and in each function definition.  But there is more to the
story than that, obviously.  What other vestigial code does it detect?
Every string literal?  Variables of the form __xxx__, I gather?  Which of
these variables have a special meaning?  How does it divide the initial
string literal into the "name" and "description" sections?  What other
directives can I send to pydoc to alter its presentation?

For instance, I might want a revision history for each module listed
before the description.  Is there a way to do that?  Or I might want
to suppress the __xxx__ variables used by pydoc from the data section.
Is there a way to do that?  What *can* I do?

Given that it is a documentation facility, pydoc isn't all that well
documented.  :-)  At least not at this page:

    http://www.python.org/doc/current/lib/module-pydoc.html

And this is hardly better:

    pydoc /usr/lib/python2.2/pydoc.py
-- 
  /\  Greg Kuperberg (UC Davis)
 /  \
 \  / Visit the Math ArXiv Front at http://front.math.ucdavis.edu/
  \/  * All the math that's fit to e-print *