docs: Add return values and skip implicit out arguments in functions

Add gi.CallableInfo.skip_return static binding for testing if the return
value should show up in docs. Skip implicit list index arguments for out
values.

https://bugzilla.gnome.org/show_bug.cgi?id=697356

3 files changed, 34 insertions, 5 deletions

diff --git a/gi/docstring.py b/gi/docstring.py
index b4ae43c4..22fc6adf 100644
--- a/gi/docstring.py
+++ b/gi/docstring.py
@@ -130,6 +130,8 @@ def _generate_callable_info_function_signature(info):
         elif info.is_constructor():
             in_args_strs = ['cls']
 
+    hint_blacklist = ('void',)
+
     # Build a lists of indices prior to adding the docs because
     # because it is possible the index retrieved comes before in
     # argument being used.
@@ -145,7 +147,7 @@ def _generate_callable_info_function_signature(info):
             continue
         argstr = arg.get_name()
         hint = _get_pytype_hint(arg.get_type())
-        if hint not in ('void',):
+        if hint not in hint_blacklist:
             argstr += ':' + hint
         if arg.may_be_null() or i in user_data_indices:
             # allow-none or user_data from a closure
@@ -155,10 +157,24 @@ def _generate_callable_info_function_signature(info):
         in_args_strs.append(argstr)
     in_args_str = ', '.join(in_args_strs)
 
-    if out_args:
-        out_args_str = ', '.join(arg.get_name() + ':' + _get_pytype_hint(arg.get_type())
-                                 for arg in out_args)
-        return '%s(%s) -> %s' % (info.get_name(), in_args_str, out_args_str)
+    out_args_strs = []
+    return_hint = _get_pytype_hint(info.get_return_type())
+    if not info.skip_return and return_hint and return_hint not in hint_blacklist:
+        if info.may_return_null():
+            argstr += ' or None'
+        out_args_strs.append(return_hint)
+
+    for i, arg in enumerate(out_args):
+        if i in ignore_indices:
+            continue
+        argstr = arg.get_name()
+        hint = _get_pytype_hint(arg.get_type())
+        if hint not in hint_blacklist:
+            argstr += ':' + hint
+        out_args_strs.append(argstr)
+
+    if out_args_strs:
+        return '%s(%s) -> %s' % (info.get_name(), in_args_str, ', '.join(out_args_strs))
     else:
         return '%s(%s)' % (info.get_name(), in_args_str)
 
diff --git a/gi/pygi-info.c b/gi/pygi-info.c
index 2f978206..95303b82 100644
--- a/gi/pygi-info.c
+++ b/gi/pygi-info.c
@@ -730,6 +730,12 @@ _wrap_g_callable_info_may_return_null (PyGIBaseInfo *self)
 }
 
 static PyObject *
+_wrap_g_callable_info_skip_return (PyGIBaseInfo *self)
+{
+    return PyBool_FromLong (g_callable_info_skip_return (self->info));
+}
+
+static PyObject *
 _wrap_g_callable_info_get_return_attribute (PyGIBaseInfo *self, PyObject *py_name)
 {
     gchar *name;
@@ -757,6 +763,7 @@ static PyMethodDef _PyGICallableInfo_methods[] = {
     { "get_return_type", (PyCFunction) _wrap_g_callable_info_get_return_type, METH_NOARGS },
     { "get_caller_owns", (PyCFunction) _wrap_g_callable_info_get_caller_owns, METH_NOARGS },
     { "may_return_null", (PyCFunction) _wrap_g_callable_info_may_return_null, METH_NOARGS },
+    { "skip_return", (PyCFunction) _wrap_g_callable_info_skip_return, METH_NOARGS },
     { "get_return_attribute", (PyCFunction) _wrap_g_callable_info_get_return_attribute, METH_O },
     { NULL, NULL, 0 }
 };
diff --git a/tests/test_docstring.py b/tests/test_docstring.py
index 1cae95cc..e117b0dd 100644
--- a/tests/test_docstring.py
+++ b/tests/test_docstring.py
@@ -63,3 +63,9 @@ class Test(unittest.TestCase):
     def test_array_length_arg(self):
         self.assertEqual(GIMarshallingTests.array_in.__doc__,
                          'array_in(ints:list)')
+
+    def test_init_function(self):
+        # This tests implicit array length args along with skipping a
+        # boolean return
+        self.assertEqual(GIMarshallingTests.init_function.__doc__,
+                         'init_function(argv:list=None) -> argv:list')