[Doc-SIG] docstring grammar

[David Ascher]

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