GNOME Bugzilla – Bug 731452
GObject overrides documentation in its subclasses
Last modified: 2014-08-17 01:10:09 UTC
Created attachment 278200 [details] Unit test for docstrings I noticed some unexpected results when running Sphinx on my GObject-derived classes. Somehow any subclass of GObject has its __doc__ property overwriten with GObject.__doc__. Similarly in Clutter, Actor subclasses get documentation from Actor.__doc__. Attached a simple unit test.
Thanks for the testcase. We can merge this into: https://git.gnome.org/browse/pygobject/tree/tests/test_docstring.py?id=3.13.2 I think the problem here is class doc strings are implemented as read-only descriptors on the meta class for GObjects. This could probably be fixed by adding a setter which modifies cls.__dict__['__doc__'] and returns the same thing if it is not empty in the getter. https://git.gnome.org/browse/pygobject/tree/gi/types.py?id=3.13.2#n239
FWIW: This seems to make it work for me: diff -Nur /tmp/types.py /usr/lib/python2.7/dist-packages/gi/types.py --- /tmp/types.py 2014-08-16 23:34:45.273230816 +0200 +++ /usr/lib/python2.7/dist-packages/gi/types.py 2014-08-16 23:33:34.565231460 +0200 @@ -227,7 +227,8 @@ def __doc__(cls): if cls == GObjectMeta: return '' - return generate_doc_string(cls.__info__) + doc = cls.__dict__.get('__doc__', generate_doc_string(cls.__info__)) + return doc def mro(C):
Committed a variation that only generates doc strings for classes coming from gi.repository or gi.overrides (constructor docs don't make sense for sub-classes with or without a doc string). Also created separate ticket for a related bug of trying to set the __doc__ attribute explicitly (bug 734926) and added a failing test. The following fixes have been pushed: https://git.gnome.org/browse/pygobject/commit/?id=4cdca43 https://git.gnome.org/browse/pygobject/commit/?id=7076669