[Python-Dev] PEP 224 (Attribute Docstrings)

[M.-A. Lemburg]

Guido van Rossum wrote:
> 
> Marc-Andre:
> > I can take over the coercion PEP: I've been working
> > on this before (see the proposal on my Python Pages).
> 
> Thanks, excellent (although I haven't seen your proposal yet).
> 
> > I would also like to know whether the PEP-0224 will be considered
> > for 2.1 if I update the patch to make it a little more robust
> > w/r to the problems mentioned in that PEP -- I'd really like
> > to see this in Python soon, since it makes documenting Python
> > programs so much easier.
> 
> I "kinda" like the idea of having attribute docstrings (meaning it's
> not of great importance to me) but there are two things I don't like
> in your current proposal:
> 
> 1. The syntax you propose is too ambiguous: as you say, stand-alone
>    string literal are used for other purposes and could suddenly
>    become attribute docstrings.

This can be fixed by introducing some extra checks in the
compiler to reset the "doc attribute" flag in the compiler
struct.
 
> 2. I don't like the access method either (__doc_<attrname>__).

Any other name will do. It will only have to match these
criteria:

* must start with two underscores (to match __doc__)
* must be extractable using some form of inspection (e.g. by using
  a naming convention which includes some fixed name part)
* must be compatible with class inheritence (i.e. should be
  stored as attribute)

> > Note that I won't get around to do much work on these before
> > January... way too busy at the moment :-/
> 
> That's a problem -- we really want to have the PEPs ready for review
> by mid December.  This will also be a problem for the coercion PEP --
> if you think you won't be able to work on it before then, I'd prefer
> to find another (co-)author.

I think I'll need a co-author for the PEPs -- I have high-priority
project running which has a deadline in mid-December too.

Much food-for-thought is already available (see the PEP 214 and
the coercion proposal on my Python Pages) and I should find
time for some review.

-- 
Marc-Andre Lemburg
______________________________________________________________________
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/