[Zope3-dev] initial topics for z3 doc project

[Guido Wesdorp]

On Friday 08 November 2002 19:19, Jeffrey P Shell wrote:
>
> 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.
>
Ehrm, I'd like some info about the datatypes of the arguments, I know Pyt=
hon=20
is not statically typed and would never want to change this, but for=20
documentation purposes in some cases it would be nice to at least know wh=
at a=20
function/method can handle...

>  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!)
>
Although this would at least be a start...

> There's also the more elaborate PEP 287 which discusses a
> reStructuredText docstring format
> (http://www.python.org/peps/pep-0287.html).
>
Hmm... To me this sounds more or less off-topic, or at least confusing an=
d=20
maybe even overkill... It doesn't matter at all to me whether we use=20
Structured Text, plain text or even XML, as long as there are some rules =
that=20
make them processable in some automatic way. Don't get me wrong, it would=
=20
probably make sense to not only make docstrings in some way more consiste=
nt,=20
but also nicer to look at or even defining some layout, but to me this is=
 not=20
what we're having problems with right now. As soon as the docstrings are =
more=20
or less written in the same manner we can (more or less) show them any wa=
y we=20
choose in any case...

> If there are going to be any "conventions", we should probably start
> from the PEPs.
>
I agree with that, let's not be reinventing the wheel. I'll have a look a=
t the=20
PEPs before the sprint, maybe I can even find the time to write some note=
s on=20
where they differ and overlap, we can then use those to start with (if us=
eful=20
enough).

Guido