SF bug 542984.

Change type_get_doc (the get function for __doc__) to look in tp_dict
more often, and if it finds a descriptor in tp_dict, to call it (with
a NULL instance).  This means you can add a __doc__ descriptor to a
new-style class that returns instance docs when called on an instance,
and class docs when called on a class -- or the same docs in either
case, but lazily computed.

I'll also check this into the 2.2 maintenance branch.

Lib/test/test_descr.py

@@ -2955,6 +2955,25 @@ def imulbug():
     y *= "foo"
     vereq(y, (x, "foo"))
 
+def docdescriptor():
+    # SF bug 542984
+    if verbose: print "Testing __doc__ descriptor..."
+    class DocDescr(object):
+        def __get__(self, object, otype):
+            if object:
+                object = object.__class__.__name__ + ' instance'
+            if otype:
+                otype = otype.__name__
+            return 'object=%s; type=%s' % (object, otype)
+    class OldClass:
+        __doc__ = DocDescr()
+    class NewClass(object):
+        __doc__ = DocDescr()
+    vereq(OldClass.__doc__, 'object=None; type=OldClass')
+    vereq(OldClass().__doc__, 'object=OldClass instance; type=OldClass')
+    vereq(NewClass.__doc__, 'object=None; type=NewClass')
+    vereq(NewClass().__doc__, 'object=NewClass instance; type=NewClass')
+
 def test_main():
     class_docstrings()
     lists()
@@ -3019,6 +3038,7 @@ def test_main():
     pickleslots()
     funnynew()
     imulbug()
+    docdescriptor()
     if verbose: print "All OK"
 
 if __name__ == "__main__":