On Tue, 2012-01-24 at 13:57 -0700, Tom Tromey wrote:
This fixes issue #31 by documenting a couple of fields of
IntegerType.
The bug is just that min_value and max_value are not documented.
Thanks; I added
:py:class: to turn it into a cross-reference and
committed (although the IntegerCst doesn't have a full entry yet).
I looked and all the other fields are documented.
It would be nice if there were a way to verify that each field or method
is also documented, so that "make" would fail if something were missing.
Agreed.
Offhand I am not sure how best to do this.
FWIW, Sphinx has
some ability to slurp information out of docstrings:
http://sphinx.pocoo.org/ext/autodoc.html
however this has some drawbacks:
(a) sphinx would have to be able to "import gcc", and that would mean
running sphinx from inside gcc. That would complicate the build, and
I'm not keen on doing this; it also stops us using the readthedocs
service.
(b) docstrings give us coverage of API entrypoints, but typically don't
give the high-level descriptions, usage examples etc. [see Jacob
Kaplan-Moss' excellent PyCon 2011 talk on writing great API
documentation, especially the "good documentation is fractal" idea].
Ideas welcome.
Dave