[Note: Please CC: all messages on this thread to me directly as I
am the PEP maintainer. If you don't, then I might not read your
comments.]
David Goodger wrote:
>
> Some comments:
>
> 1. I think the idea of attribute docstrings is a great one. It would assist
> in the auto-documenting of code immeasurably.
Agreed ;-)
> 2. I second Frank Niessink (frankn=nuws@cs.vu.nl), who wrote:
>
> > wouldn't the naming
> > scheme <attributename>.__doc__ be a better one?
> >
> > So if:
> >
> > class C:
> > a = 1
> > """Description of a."""
> >
> > then:
> >
> > C.a.__doc__ == "Description of a."
>
> 'C.a.__doc__' is far more natural and Pythonic than 'C.__doc__a__'. The
> latter would also require ugly tricks to access.
This doesn't work, since Python objects cannot have arbitrary
attributes. Also, I wouldn't want to modify attribute objects indirectly
from the outside as the above implies.
I don't really see the argument of __doc__a__ being hard to
access: these attributes are meant for tools to use, not
humans ;-), and these tools can easily construct the right
lookup names by scanning the dir(obj) and then testing for
the various __doc__xxx__ strings.
> 3. However, what would happen to C.a.__doc__ (or C.__doc__a__ for that
> matter) when attribute 'a' is reassigned? For example:
>
> class C:
> a = 1 # class attribute, default value for instance attribute
> """Description of a."""
>
> def __init__(self, arg=None):
> if arg is not None:
> self.a = arg # instance attribute
> self.b = []
> """Description of b."""
>
> instance = C(2)
>
> What would instance.a.__doc__ (instance.__doc__a__) be? Would the __doc__ be
> wiped out by the reassignment, or magically remain unless overridden?
See above. This won't work.
> 4. How about instance attributes that are never class attributes? Like
> 'instance.b' in the example above?
I don't get the point... doc strings should always be considered
constant and thus be defined in the class/module definition.
> 5. Since docstrings "belong" to the attribute preceeding them, wouldn't it
> be more Pythonic to write:
>
> class C:
> a = 1
> """Description of a."""
>
> ? (In case of mail viewer problems, each line above is indented relative to
> the one before.) This emphasizes the relationship between the docstring and
> the attribute. Of course, such an approach may entail a more complicated
> modification to the Python source, but also more complete IMHO.
Note that Python's indents block and these are always preceeded
by a line ending in a colon. The above idea would break this.
> 6. Instead of mangling names, how about an alternative approach? Each class,
> instance, module, and function gets a single special name (call it
> '__docs__' for now), a dictionary of attribute-name to docstring mappings.
> __docs__ would be the docstring equivalent to __dict__. These dictionary
> entries would not be affected by reassignment unless a new docstring is
> specified. So, in the example from (3) above, we would have:
>
> >>> instance.__docs__
> {'b': 'Description of b.'}
> >>> C.__docs__
> {'a': 'Description of a.'}
>
> Just as there is a built-in function 'dir' to apply Inheritance rules to
> instance.__dict__, there would have to be a function 'docs' to apply
> inheritance to instance.__docs__:
>
> >>> docs(instance)
> {'a': 'Description of a.', 'b': 'Description of b.'}
>
> There are repercussions here. A module containing the example from (3) above
> would have a __docs__ dictionary containing mappings for docstrings for each
> top-level class and function defined, in addition to docstrings for each
> global variable.
This would not work well together with class inheritance.
> In conclusion, although this proposal has great promise, it still needs
> work. If it's is to be done at all, better to do it right.
>
> This could be the first true test of the PEP system; getting input from the
> Python user community as well as the core PythonLabs and Python-Dev groups.
> Other PEPs have been either after-the-fact or, in the case of those features
> approved for inclusion in Python 2.0, too rushed for a significant
> discussion.
We'll see whether this "global" approach is a good one ;-)
In any case, I think it'll give more awareness of the PEP
system.
Thanks for the comments,
--
Marc-Andre Lemburg
______________________________________________________________________
Business: http://www.lemburg.com/
Python Pages: http://www.lemburg.com/python/
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4