classification
Title: Add doc-string to UserDict and DictMixin
Type: Stage:
Components: Documentation Versions: Python 2.6
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: belopolsky, rhettinger
Priority: normal Keywords: patch

Created on 2008-02-24 05:09 by belopolsky, last changed 2008-03-24 17:19 by belopolsky. This issue is now closed.

Files
File name Uploaded Description Edit
UserDict-doc.diff belopolsky, 2008-02-24 05:09
UserDict-doc.diff belopolsky, 2008-02-24 05:19
Messages (4)
msg62876 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2008-02-24 05:09
Attached patch improves pydoc UserDict presentation.

One of the problems with the current documentation in comments is that 
order of methods is not preserved and thus the method level comments in 
DictMixin implementation are meaningless in pydoc. (In any case the 
comments are not accurate even in the source file.)

If this patch is accepted in principle, the original level comments 
should be removed.  I am leaving them intact to simplify the review.
msg62877 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2008-02-24 05:21
Fixed an error in lavels doc.  Needs review.
msg64404 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2008-03-24 08:53
I'm not sure the class docstring approach is suitable for a mixin.  It 
seems fine to me that pydoc strips the commentary on the mixin as a 
standalone class; instead it appropriately focuses on the client class 
that uses the mixin as part of its API.

FWIW, all of this code goes away in Py3.0.
msg64423 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2008-03-24 17:19
On Mon, Mar 24, 2008 at 4:53 AM, Raymond Hettinger
<report@bugs.python.org> wrote:

>  I'm not sure the class docstring approach is suitable for a mixin.  It
>  seems fine to me that pydoc strips the commentary on the mixin as a
>  standalone class;

My main point was not that some commentary was stripped by
pydoc, but that the commentary that is not stripped is misleading:

The beginning of pydoc UserDict.DictMixin is rendered as follows:

UserDict.DictMixin = class DictMixin
 |  Methods defined here:
 |
 |  __cmp__(self, other)
 |
 |  __contains__(self, key)
 |
 |  __iter__(self)
 |      # second level definitions support higher levels
 |
 |  __len__(self)
..

What does "second level definitions support higher levels" comment
below __iter__ means? Does it apply to all methods above or all
methods below but above the "third level ..." comment or just to
__iter__?  All of these plausible interpretations are wrong.

Furthemore, pydoc UserDict is rendered as follows:

NAME
    UserDict - A more or less complete user-defined wrapper around
dictionary objects.

FILE
    /bnv/home/abelopolsky/Work/python-svn/trunk/Lib/UserDict.py

CLASSES
    DictMixin
    UserDict
        IterableUserDict

    class DictMixin
...

Which is not helpful at all in understanding of what DictMixin is for.

> instead it appropriately focuses on the client class
>  that uses the mixin as part of its API.

I assume you refer to UserDict as the "client class". In what sense
does it use "mixin as part of its API"?  In 2.x, UserDict does not
derive from DictMixin.  To the contrary, UserDict and DictMixin
present quite different APIs to the users of derived classes.  For
example, overriding __getitem__  does not affect  has_key,
__contains__ or iter* methods of the class deriving from UserDict,
which is different from the way DictMixin descendants work.

.. that's why I selected version 2.6 when I submitted this issue. :-)

However, AFAICT, not all this code goes away, just UserDict is
moved to collections and DictMixin functionality is replaced with
ABCs.   This is a welcome change because with abstract
methods the classes become self-documenting, but I have to
note that UserDict will behave differently in 3.0:  the following
code  print 1 in 2.x and 42 in 3.0:

class X(UserDict):
    def __getitem__(self, _):
        return 42

print(X(a=1).pop('a'))

This change should probably be reflected in the docs
somewhere.
History
Date User Action Args
2008-03-24 17:19:15belopolskysetmessages: + msg64423
2008-03-24 08:53:20rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg64404
2008-02-24 07:00:16rhettingersetassignee: rhettinger
nosy: + rhettinger
2008-02-24 05:22:46belopolskysetcomponents: + Documentation
versions: + Python 2.6
2008-02-24 05:21:04belopolskysetmessages: + msg62877
2008-02-24 05:19:45belopolskysetfiles: + UserDict-doc.diff
2008-02-24 05:09:31belopolskycreate