[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gcc-python-plugin
Subject:    fix issue #31
From:       dmalcolm () redhat ! com (David Malcolm)
Date:       2012-02-02 1:46:01
Message-ID: 1328147162.18775.22.camel () surprise
[Download RAW message or body]

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


[prev in list] [next in list] [prev in thread] [next in thread]