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.

Fixed an error in lavels doc.  Needs review.

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.

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.