[ python-Bugs-856072 ] UserDict.DictMixin's comments should be a docstring

[SourceForge.net]

Bugs item #856072, was opened at 2003-12-08 17:19
Message generated for change (Comment added) made by spiv
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=856072&group_id=5470

Category: Python Library
Group: None
>Status: Closed
>Resolution: Invalid
Priority: 5
Submitted By: Andrew Bennetts (spiv)
Assigned to: Raymond Hettinger (rhettinger)
Summary: UserDict.DictMixin's comments should be a docstring

Initial Comment:
DictMixin in the UserDict module has no docstring --
but it has a comment that reads like one.  I think the
comment should probably be changed to a docstring so
that interactive use of e.g. "help(UserDict.DictMixin)"
explains how it works (override _getitem__(),
__setitem__(), __delitem__(), and keys(), and the rest
is done for you).

If the existing comment is considered too cryptic, the
text in the Library Reference for DictMixin would be a
good basis for a docstring.

(This is a really minor bug, but it's a shame to see
such a useful class not being perfectly documented! :)

----------------------------------------------------------------------

>Comment By: Andrew Bennetts (spiv)
Date: 2003-12-22 11:36

Message:
Logged In: YES 
user_id=50945

I'm happy to trust your judgement on this.  The library
reference docs should be the primary reference rather than
the docstring, after all.

Thanks!

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2003-12-22 08:24

Message:
Logged In: YES 
user_id=80475

After thinking about it for a while, I would like to stick with 
the original decision.  If you agree, please mark as Invalid 
and close the bug report.

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2003-12-15 03:43

Message:
Logged In: YES 
user_id=80475

Okay, I'll take another look at the original decision to
omit docstrings.  The rationale was to avoid contaminating
the documentation of user classes that subclass
UserDict.DictMixin.


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=856072&group_id=5470