giscanner: Mark (closure) parameters as (nullable) by convention

All user_data pointers should be nullable, and they should all be
annotated as closures too. I have not found any counter-examples where a
closure is non-nullable.

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

3 files changed, 107 insertions, 20 deletions

diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py
index bb79a5b3..8bac1430 100644
--- a/giscanner/maintransformer.py
+++ b/giscanner/maintransformer.py
@@ -1438,6 +1438,13 @@ method or constructor of some type."""
                   param.argname is not None and
                   param.argname.endswith('data')):
                 callback_param.closure_name = param.argname
+                param.closure_name = param.argname
+
+        for param in params:
+            # By convention, closure user_data parameters are always nullable.
+            if param.closure_name is not None and \
+               param.closure_name == param.argname:
+                param.nullable = True
 
     def _pass3_callable_throws(self, node):
         """Check to see if we have anything that looks like a
diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir
index 55586c4f..b856867f 100644
--- a/tests/scanner/Regress-1.0-expected.gir
+++ b/tests/scanner/Regress-1.0-expected.gir
@@ -136,7 +136,11 @@ and/or use gtk-doc annotations.  -->
         <parameter name="item" transfer-ownership="none">
           <type name="utf8" c:type="const char*"/>
         </parameter>
-        <parameter name="user_data" transfer-ownership="none" closure="2">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="2">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>
@@ -166,7 +170,11 @@ and/or use gtk-doc annotations.  -->
         <type name="none" c:type="void"/>
       </return-value>
       <parameters>
-        <parameter name="data" transfer-ownership="none" closure="0">
+        <parameter name="data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="0">
           <doc xml:space="preserve">The user data</doc>
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
@@ -376,7 +384,11 @@ are zero-terminated</doc>
             <type name="AnnotationForeachFunc"
                   c:type="RegressAnnotationForeachFunc"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     nullable="1"
+                     allow-none="1"
+                     closure="1">
             <doc xml:space="preserve">Callback user data</doc>
             <type name="gpointer" c:type="gpointer"/>
           </parameter>
@@ -724,7 +736,11 @@ regress_annotation_object_watch_full().</doc>
             <type name="AnnotationForeachFunc"
                   c:type="RegressAnnotationForeachFunc"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     nullable="1"
+                     allow-none="1"
+                     closure="1">
             <doc xml:space="preserve">The callback data</doc>
             <type name="gpointer" c:type="gpointer"/>
           </parameter>
@@ -751,7 +767,11 @@ regress_annotation_object_watch_full().</doc>
             <type name="AnnotationForeachFunc"
                   c:type="RegressAnnotationForeachFunc"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     nullable="1"
+                     allow-none="1"
+                     closure="1">
             <doc xml:space="preserve">The callback data</doc>
             <type name="gpointer" c:type="gpointer"/>
           </parameter>
@@ -1797,7 +1817,11 @@ exposed to language bindings.</doc>
                      closure="1">
             <type name="GObject.Callback" c:type="GCallback"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none" closure="1">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     nullable="1"
+                     allow-none="1"
+                     closure="1">
             <type name="gpointer" c:type="gpointer"/>
           </parameter>
         </parameters>
@@ -1826,7 +1850,11 @@ exposed to language bindings.</doc>
                      closure="1">
             <type name="GObject.Callback" c:type="GCallback"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     nullable="1"
+                     allow-none="1"
+                     closure="1">
             <type name="gpointer" c:type="gpointer"/>
           </parameter>
         </parameters>
@@ -1882,7 +1910,11 @@ exposed to language bindings.</doc>
                        closure="2">
               <type name="GObject.Callback" c:type="GCallback"/>
             </parameter>
-            <parameter name="user_data" transfer-ownership="none" closure="2">
+            <parameter name="user_data"
+                       transfer-ownership="none"
+                       nullable="1"
+                       allow-none="1"
+                       closure="2">
               <type name="gpointer" c:type="gpointer"/>
             </parameter>
           </parameters>
@@ -2402,7 +2434,11 @@ use it should be.</doc>
         <type name="gint" c:type="int"/>
       </return-value>
       <parameters>
-        <parameter name="user_data" transfer-ownership="none" closure="0">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="0">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>
@@ -2873,7 +2909,11 @@ use it should be.</doc>
             <type name="TestCallbackUserData"
                   c:type="RegressTestCallbackUserData"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     nullable="1"
+                     allow-none="1"
+                     closure="1">
             <type name="gpointer" c:type="gpointer"/>
           </parameter>
           <parameter name="notify" transfer-ownership="none" scope="async">
@@ -4251,7 +4291,11 @@ detection, and fixing it via annotations.</doc>
           <type name="AnnotationNotifyFunc"
                 c:type="RegressAnnotationNotifyFunc"/>
         </parameter>
-        <parameter name="data" transfer-ownership="none">
+        <parameter name="data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="2">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>
@@ -4445,7 +4489,11 @@ detection, and fixing it via annotations.</doc>
                    closure="2">
           <type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/>
         </parameter>
-        <parameter name="user_data" transfer-ownership="none">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="2">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>
@@ -4463,7 +4511,11 @@ detection, and fixing it via annotations.</doc>
                    destroy="2">
           <type name="FooCallback" c:type="RegressFooCallback"/>
         </parameter>
-        <parameter name="data" transfer-ownership="none">
+        <parameter name="data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="1">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
         <parameter name="destroy" transfer-ownership="none" scope="async">
@@ -5334,7 +5386,11 @@ libgnome-keyring.</doc>
           <type name="TestCallbackUserData"
                 c:type="RegressTestCallbackUserData"/>
         </parameter>
-        <parameter name="user_data" transfer-ownership="none">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="1">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>
@@ -5355,7 +5411,11 @@ is invoked.</doc>
           <type name="TestCallbackUserData"
                 c:type="RegressTestCallbackUserData"/>
         </parameter>
-        <parameter name="user_data" transfer-ownership="none">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="1">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
         <parameter name="notify" transfer-ownership="none" scope="async">
@@ -5426,7 +5486,11 @@ call and can be released on return.</doc>
           <type name="TestCallbackUserData"
                 c:type="RegressTestCallbackUserData"/>
         </parameter>
-        <parameter name="user_data" transfer-ownership="none">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="1">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>
@@ -6435,7 +6499,11 @@ https://bugzilla.gnome.org/show_bug.cgi?id=685399</doc>
           <type name="TestCallbackUserData"
                 c:type="RegressTestCallbackUserData"/>
         </parameter>
-        <parameter name="user_data" transfer-ownership="none">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="2">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
         <parameter name="notify" transfer-ownership="none" scope="async">
diff --git a/tests/scanner/Utility-1.0-expected.gir b/tests/scanner/Utility-1.0-expected.gir
index 0bd38297..38b6a3cb 100644
--- a/tests/scanner/Utility-1.0-expected.gir
+++ b/tests/scanner/Utility-1.0-expected.gir
@@ -55,7 +55,11 @@ and/or use gtk-doc annotations.  -->
         <parameter name="path" transfer-ownership="none">
           <type name="utf8" c:type="const char*"/>
         </parameter>
-        <parameter name="user_data" transfer-ownership="none" closure="1">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="1">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>
@@ -93,7 +97,11 @@ and/or use gtk-doc annotations.  -->
                      destroy="3">
             <type name="FileFunc" c:type="UtilityFileFunc"/>
           </parameter>
-          <parameter name="user_data" transfer-ownership="none">
+          <parameter name="user_data"
+                     transfer-ownership="none"
+                     nullable="1"
+                     allow-none="1"
+                     closure="2">
             <type name="gpointer" c:type="gpointer"/>
           </parameter>
           <parameter name="destroy" transfer-ownership="none" scope="async">
@@ -169,7 +177,11 @@ and/or use gtk-doc annotations.  -->
                    closure="2">
           <type name="FileFunc" c:type="UtilityFileFunc"/>
         </parameter>
-        <parameter name="user_data" transfer-ownership="none">
+        <parameter name="user_data"
+                   transfer-ownership="none"
+                   nullable="1"
+                   allow-none="1"
+                   closure="2">
           <type name="gpointer" c:type="gpointer"/>
         </parameter>
       </parameters>