[pygobject] docs: List constructors in object and struct doc strings

[Simon Feltman <sfeltman src gnome org>]

commit 9bfd73e7c3f2ec4975b3e530ba7c2cc55ee793d5
Author: Simon Feltman <sfeltman src gnome org>
Date:   Wed Jan 1 17:34:32 2014 -0800

    docs: List constructors in object and struct doc strings
    
    Add type dispatching to gi.docstring documentation generator for info types
    of StructInfo and ObjectInfo. Add lazy doc string generation to
    Object and Struct meta classes by using a property for __doc__. This lists
    available constructors immediately in all GObject.Object and Struct docs.
    ipython example:
    
    >>> Gtk.Button?
    :Constructors:
        Button(**properties)
        new()
        new_from_icon_name(icon_name:str, size:int)
        new_from_stock(stock_id:str)
        new_with_label(label:str)
        new_with_mnemonic(label:str)
    
    https://bugzilla.gnome.org/show_bug.cgi?id=708060

 gi/docstring.py         |   36 +++++++++++++++++++++++++++++-------
 gi/types.py             |    9 +++++++++
 tests/test_docstring.py |    8 ++++++++
 3 files changed, 46 insertions(+), 7 deletions(-)
---
diff --git a/gi/docstring.py b/gi/docstring.py
index 22fc6ad..6141b5a 100644
--- a/gi/docstring.py
+++ b/gi/docstring.py
@@ -23,6 +23,9 @@
 from ._gi import \
     VFuncInfo, \
     FunctionInfo, \
+    CallableInfo, \
+    ObjectInfo, \
+    StructInfo, \
     Direction, \
     TypeTag
 
@@ -118,8 +121,7 @@ def _get_pytype_hint(gi_type):
     return gi_type.get_tag_as_string()
 
 
-def _generate_callable_info_function_signature(info):
-    """Default doc string generator"""
+def _generate_callable_info_doc(info):
     in_args, out_args = split_function_info_args(info)
     in_args_strs = []
     if isinstance(info, VFuncInfo):
@@ -127,8 +129,6 @@ def _generate_callable_info_function_signature(info):
     elif isinstance(info, FunctionInfo):
         if info.is_method():
             in_args_strs = ['self']
-        elif info.is_constructor():
-            in_args_strs = ['cls']
 
     hint_blacklist = ('void',)
 
@@ -174,9 +174,31 @@ def _generate_callable_info_function_signature(info):
         out_args_strs.append(argstr)
 
     if out_args_strs:
-        return '%s(%s) -> %s' % (info.get_name(), in_args_str, ', '.join(out_args_strs))
+        return '%s(%s) -> %s' % (info.__name__, in_args_str, ', '.join(out_args_strs))
     else:
-        return '%s(%s)' % (info.get_name(), in_args_str)
+        return '%s(%s)' % (info.__name__, in_args_str)
 
 
-set_doc_string_generator(_generate_callable_info_function_signature)
+def _generate_class_info_doc(info):
+    doc = ''
+    constructors = [method for method in info.get_methods() if method.is_constructor()]
+    if constructors:
+        doc += '\n:Constructors:\n'  # start with \n to avoid auto indent of other lines
+
+        for method_info in constructors:
+            doc += '    ' + _generate_callable_info_doc(method_info) + '\n'
+
+    return doc
+
+
+def _generate_doc_dispatch(info):
+    if isinstance(info, (ObjectInfo, StructInfo)):
+        return _generate_class_info_doc(info)
+
+    elif isinstance(info, CallableInfo):
+        return _generate_callable_info_doc(info)
+
+    return ''
+
+
+set_doc_string_generator(_generate_doc_dispatch)
diff --git a/gi/types.py b/gi/types.py
index 7c0f617..41efc05 100644
--- a/gi/types.py
+++ b/gi/types.py
@@ -28,6 +28,7 @@ import warnings
 from . import _gobject
 from ._gobject._gobject import GInterface
 from ._gobject.constants import TYPE_INVALID
+from .docstring import generate_doc_string
 
 from ._gi import \
     InterfaceInfo, \
@@ -196,6 +197,10 @@ class GObjectMeta(_gobject.GObjectMeta, MetaClassHelper):
     def mro(cls):
         return mro(cls)
 
+    @property
+    def __doc__(cls):
+        return generate_doc_string(cls.__info__)
+
 
 def mro(C):
     """Compute the class precedence list (mro) according to C3, with GObject
@@ -276,3 +281,7 @@ class StructMeta(type, MetaClassHelper):
                     not method_info.get_arguments():
                 cls.__new__ = staticmethod(method_info)
                 break
+
+    @property
+    def __doc__(cls):
+        return generate_doc_string(cls.__info__)
diff --git a/tests/test_docstring.py b/tests/test_docstring.py
index e117b0d..71f1b83 100644
--- a/tests/test_docstring.py
+++ b/tests/test_docstring.py
@@ -69,3 +69,11 @@ class Test(unittest.TestCase):
         # boolean return
         self.assertEqual(GIMarshallingTests.init_function.__doc__,
                          'init_function(argv:list=None) -> argv:list')
+
+    def tests_class_doc_constructors(self):
+        doc = GIMarshallingTests.Object.__doc__
+        self.assertTrue('new(int_:int)' in doc)
+
+    def tests_struct_doc_constructors(self):
+        doc = GIMarshallingTests.BoxedStruct.__doc__
+        self.assertTrue('new()' in doc)