[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[Samuele Pedroni]

[Guido]
> > The primary/secondary splitting (not possible in CL), does
> > not change this because *in the code*, they end up in the same
> > place and count visually anyway as one *long* docstring.
> 
> But note that there are other points of view.  I don't mind if some
> package author wants to keep all the docs together with the code and
> wants to stick it all in the docstrings, and run some tool that
> extracts the docs and formats them as a reference manual.  That's just
> not how I want to manage the standard library docs.
> 

Yup, but the final point is that easy to make happy  also people
that want to split the doc between the short informative
docstring and a longish comment in front of the definition,
and have the auto-doc extraction support this with 
reasonable options (extracting both things or just one).

You can dislike this different approach, because the
comment/docstring can be redundant or because, trying
to avoid this, the reading vs. spatial orders of the two 
will not match. 

Personally I can see myself using this approach sometimes,
it does not hurt my sensibility too much.

It's very hard to come up with strong arguments
wrt to these issues.

working-for-a-peaceful-cohabitation-expressing-the-point-
of-view-of-a-(maybe-1-person)-minority-ly y'rs, Samuele.