[Doc-SIG] Re: [Docstring-develop] Attribute docstrings

[David Goodger]

Tony J Ibbs (Tibs) <tony@lsl.co.uk> wrote on 2001-08-16 09:42:
> 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?

The fundamental differences between PEP 224 and the relevant part of
PEP 258 are the impact and the context. PEP 224 required changes to
the core Python language for a feature of marginal usefulness *to* the
core language. The DPS (PEP 258) provides a useful, application
context for the concept of attribute docstrings, without requiring any
changes to the core Python language. Attribute docstrings become a
simple documentation convention with no impact or incompatibilities.

Although I think attribute docstrings are very useful (see
dps/statemachine.py for a complete example), the success of the DPS
does not hinge on them being accepted. If push comes to shove, they're
easy to drop. But I hope it doesn't come to that, since it's really an
application issue.

> 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

Nor do I; I don't think any of these would fly. If forced to use such
markup, I think I'd rather just leave these docstrings in the parent
module/class/method/function docstring.

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

If we can glean this info from the AST, then that's certainly a
possibility.

> do we have a BDFL comment on this part of the DPS spec?

Let's ask. What do you think, Guido?

-- 
David Goodger    dgoodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net