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