[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

Samuele Pedroni pedroni@inf.ethz.ch
Sat, 6 Apr 2002 23:46:00 +0200

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

of-view-of-a-(maybe-1-person)-minority-ly y'rs, Samuele.