[Zope3-dev] initial topics for z3 doc project

[holger krekel]

Jeffrey P Shell wrote:
> On Thursday, November 7, 2002, at 03:45  PM, holger krekel wrote:
> > We could write a unittest for "correct" syntax of docstrings.
> > Coincidentally, I talked to GvR about some python docstrings
> > and a stricter syntax regarding the 'signature' line (the first
> > of a docstring).
> 
> There's a whole suite of PEPs about docstrings, and PEP 257 (DocString
> conventions) admonishes having a signature line:
> 
> - The one-line docstring should NOT be a "signature" reiterating the
>    function/method parameters (which can be obtained by introspection).

Yes, i wasn't giving enough context.  Of course full signatures are 
only useful with C-implementations. You can introspect the signature
from a python callable relatively easy (if it doesn't use
*args,**kwargs).

> There's also the more elaborate PEP 287 which discusses a 
> reStructuredText docstring format 
> (http://www.python.org/peps/pep-0287.html).

That's what i would first aim for.  With python reStructuredText gains
a lot of popularity, recently (IMHO, of course). 

> If there are going to be any "conventions", we should probably start 
> from the PEPs.

Yep.

    holger