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

3 files changed, 46 insertions, 7 deletions

diff --git a/gi/docstring.py b/gi/docstring.py
index 22fc6adf..6141b5ac 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 7c0f617d..41efc051 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 e117b0dd..71f1b838 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)