[Doc-SIG] docstring grammar
David Ascher
da@ski.org
Fri, 3 Dec 1999 22:18:54 -0800 (Pacific Standard Time)
On Fri, 3 Dec 1999, Guido van Rossum wrote:
> > Paul Prescod writes:
> > > What I'm hearing is that C extensions should just NOT be documented
> > > inline. Perhaps the interperter should look for their docstrings in .pdc
> > > files...to be defined another day!!!
>
> Fred Drake:
> > Perhaps a reasonable approach would be to write the documentation as
> > a Python source file that offered right interface and some sort of
> > flag that the classes are really extension types? This would make it
> > reasonably easy to work with and explain, and no new markup language
> > has to be introduced simply to document an extension module.
>
> I experimented with this for the threading module. Java also does
> this for native methods (which always have a stub declaring their
> types in a Java class file).
But I think it's crucial that IDEs for example can find out what the
signature for functions defined in extension modules is. So, I'm going to
propose:
look for module_doc.py
if found: use it
else:
if user_allows_imports:
import module and use introspection (e.g. __doc__)
else:
tough.
Some users trust the code, some don't. This way what the tool provides is
up to the user.
[ ] Enable JavaScript
[ ] Enable Cookies
[ ] Enable Java
[ ] Enable Python Import
Which brings up the question of whether we want to associate RSA
certificates with modules. JUST KIDDING!
--da