[Zope3-dev] initial topics for z3 doc project

[Jeffrey P Shell]

On Thursday, November 7, 2002, at 03:45  PM, holger krekel wrote:

> Guido Wesdorp wrote:
>> On Thursday 07 November 2002 10:51, holger krekel wrote:
>>>
>>> If all 'documentation' is available at runtime this makes it
>>> easier to have interactive search functions etc.  Maybe the
>>> Demo-Project project should really be a Zope3 product itself
>>> documenting itself.  Eat your own catfood.
>>> But that might mean we have to wait :-)
>>>
>> Do one of you know how well the sources itself are documented? It 
>> would help
>> if the docstrings would be a little more consistent then in 2... 
>> Maybe we can
>> make sure extracting documentation from the sources will lead to a 
>> clean and
>> complete reference,  making sure arguments, returnvalues etc. are 
>> described
>> in the docstrings of either the objects or the interfaces in a 
>> consistent
>> manner. Or at least set some obligatory style for docstrings or so...
>
> 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).
   Don't do::

       def function(a, b):
           """function(a, b) -> list"""

   This type of docstring is only appropriate for C functions (such as
   built-ins), where introspection is not possible.  However, the
   nature of the *return value* cannot be determined by introspection,
   so it should be mentioned.  The preferred form for such a docstring
   would be something like::

       def function(a, b):
           """Do X and return a list."""

   (Of course "Do X" should be replaced by a useful description!)

.. source:: http://www.python.org/peps/pep-0257.html

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

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