Proposal to extend PEP 257 (New Documentation String Spec)

[rantingrick]

On Jul 15, 2:13 am, Chris Angelico <ros... at gmail.com> wrote:
> On Fri, Jul 15, 2011 at 9:02 AM, rantingrick <rantingr... at gmail.com> wrote:
> > Too many folks
> > are refusing to document properly and so i will take this time to
> > hammer out a spec.
>
> The tighter you squeeze your fist, Lord Rick, the more star
> programmers will slip through your fingers.
>
> Make it so docstrings HAVE to be in a particular format, and people
> will stop writing docstrings. Make it so Python functions HAVE to have
> docstrings, and people will stop writing Python functions.

Hmm, that's strange considering that code MUST be formatted in certain
ways or you get a syntax error (indention, colons, parenthesis, etc,
etc). I don't hear the masses claiming that they are going over to
Ruby simply because of indention.

In my mind doc-strings should ALWAYS be optional HOWEVER if the
programmer decides to create a doc-string THEN he must observe some
syntax rules or his code will throw an SyntaxError. Remember, freedom
is good, unbridled freedom is the root of all evil.

So what's so terrible about structure Chris? Nobody's freedom are
being taken away. You don't HAVE to create doc-strings, just like you
don't HAVE to code with Python (you do free form formatting Ruby).
Python is a language that is meant to be clean. Forced indention makes
that possible. Forced doc-string syntax will complete the circle.