[Docstring-develop] Attribute docstrings

[Tony J I. (Tibs) <to...@ls...>]

I'm sending this to the development group and not the doc-sig because
I'm not convinced it makes enough sense!

DPS (pep 258) is proposing to support attribute docstrings.

Yet PEP 224 was rejected by the BDFL because he dislikes the look of::

    a = 1
    """Documentation."""
    b = 1

a. because he doesn't like it
b. because he can't tell if the docstring belongs
   to `a` or `b`

This rejection did *not* worry about issues of what value was used to
store the docstring (obviously not an issue for us).

Is DPS on dodgy ground in supporting a PEP that has been fundamentally
rejected?

As a potential *slight* cure for the BDFL objections (I'm doubtful), I
can only propose that we mark up the docstring itself::

    a = 1
    """.. doc::a Some documentation"""

would be documentation for `a`. That's a bit verbose, so maybe it should
be::

    """:doc:a Some documentation"""

Or even::

    """:a: Some documentation"""

(is that last stretching too far?)

[I'm not sure I like any of the above, in fact - do we have a BDFL
comment on this part of the DPS spec?]

Or maybe we should enforce no blank line before the docstring, and at
least one blank line after it (I've yet to see if we can tell that from
the AST, but I suspect we can).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)