[Python-Dev] Re: What has become of PEP224 (attribute docstrings) ?

[M.-A. Lemburg]

Guido van Rossum wrote:
> ...
>
> The attribute docstring PEP didn't get in (and is unlikely to get in in its
> current form) because I don't like the syntax much, *and* because the way to
> look up the docstrings is weird and ugly: you'd have to use something like
> instance.spam__doc__ or instance.__doc__spam (I forget which; they're both
> weird and ugly).

It was the only way I could think of for having attribute doc-
strings behave in the same way as e.g. methods do, that is they
should respect the class hierarchy in much the same way. This is
obviously needed if you want to document not only the method interface
of a class, but also its attributes which could be accessible from
the outside.

I am not sure whether parsing the module would enable the same
sort of functionality unless Ping's code does it's own interpretation
of imports and base class lookups.

Note that the attribute doc string attribute names are really
secondary to the PEP. The main point is using the same syntax
for attribute doc-strings as we already use for classes, modules
and functions.

> I also expect that the doc-sig will be using the same syntax (string
> literals in non-docstring positions) for a different purpose. 

I haven't seen any mention of this on the doc-sig. Could you explain
what they intend to use them for ?

> So I see
> little chance for PEP 224.  Maybe I should just pronounce on this, and
> declare the PEP rejected.

Do you have an alternative approach which meets the design goals
of the PEP ?
 
> Unless Ping thinks this would be a really cool feature to be added to pydoc?
> (Ping's going to change pydoc from importing the target module to scanning
> its surce, I believe -- then he could add this feature without changing the
> Python parser. :-)

While Ping's code is way cool, I think we shouldn't forget that
other code will also want to do its own introspection, possibly
even at run-time which is certainly not possible by (re-)parsing the
source code every time.

-- 
Marc-Andre Lemburg
______________________________________________________________________
Company & Consulting:                           http://www.egenix.com/
Python Pages:                           http://www.lemburg.com/python/