[Doc-SIG] docstring grammar

[Guido van Rossum]

> 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).

On the downside, it decouples the doc from the source, which was the
primary motivation for docstring extraction, and perhaps writing it
directly in latex/SGML/whatever is easier than writing a dummy Python
module -- it certainly gives more control.  Plus, it's more likely
that specialized editors exist.

>   It also wouldn't hurt that no additional tools would be needed!  ;-)

But probably existing tools would have to be extended to know about
this arrangement, since it's not completely transparent.

--Guido van Rossum (home page: http://www.python.org/~guido/)