giscanner: add (nullable) and (optional) annotations

Add two new annotations, (nullable) and (optional).

(nullable) always means "the type of this value can also contain null".

(optional) always means "this out parameter can be ignored by passing
NULL to the C function".

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

2 files changed, 33 insertions, 1 deletions

diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py
index 5ded4193..a167ff94 100644
--- a/giscanner/annotationparser.py
+++ b/giscanner/annotationparser.py
@@ -201,6 +201,8 @@ ANN_GET_VALUE_FUNC = 'get-value-func'
 ANN_IN = 'in'
 ANN_INOUT = 'inout'
 ANN_METHOD = 'method'
+ANN_NULLABLE = 'nullable'
+ANN_OPTIONAL = 'optional'
 ANN_OUT = 'out'
 ANN_REF_FUNC = 'ref-func'
 ANN_RENAME_TO = 'rename-to'
@@ -788,6 +790,30 @@ class GtkDocAnnotatable(object):
 
         self._validate_annotation(position, ann_name, options, exact_n_options=0)
 
+    def _do_validate_nullable(self, position, ann_name, options):
+        '''
+        Validate the ``(nullable)`` annotation.
+
+        :param position: :class:`giscanner.message.Position` of the line in the source file
+                         containing the annotation to be validated
+        :param ann_name: name of the annotation holding the options to validate
+        :param options: annotation options held by the annotation
+        '''
+
+        self._validate_annotation(position, ann_name, options, exact_n_options=0)
+
+    def _do_validate_optional(self, position, ann_name, options):
+        '''
+        Validate the ``(optional)`` annotation.
+
+        :param position: :class:`giscanner.message.Position` of the line in the source file
+                         containing the annotation to be validated
+        :param ann_name: name of the annotation holding the options to validate
+        :param options: annotation options held by the annotation
+        '''
+
+        self._validate_annotation(position, ann_name, options, exact_n_options=0)
+
     def _do_validate_out(self, position, ann_name, options):
         '''
         Validate the ``(out)`` annotation.
diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py
index 5f4788a3..90b702d8 100644
--- a/giscanner/maintransformer.py
+++ b/giscanner/maintransformer.py
@@ -27,7 +27,7 @@ from .annotationparser import (ANN_ALLOW_NONE, ANN_ARRAY, ANN_ATTRIBUTES, ANN_CL
                                ANN_GET_VALUE_FUNC, ANN_IN, ANN_INOUT, ANN_METHOD, ANN_OUT,
                                ANN_REF_FUNC, ANN_RENAME_TO, ANN_SCOPE, ANN_SET_VALUE_FUNC,
                                ANN_SKIP, ANN_TRANSFER, ANN_TYPE, ANN_UNREF_FUNC, ANN_VALUE,
-                               ANN_VFUNC)
+                               ANN_VFUNC, ANN_NULLABLE, ANN_OPTIONAL)
 from .annotationparser import (OPT_ARRAY_FIXED_SIZE, OPT_ARRAY_LENGTH, OPT_ARRAY_ZERO_TERMINATED,
                                OPT_OUT_CALLEE_ALLOCATES, OPT_OUT_CALLER_ALLOCATES,
                                OPT_TRANSFER_FLOATING, OPT_TRANSFER_NONE)
@@ -579,6 +579,12 @@ class MainTransformer(object):
 
         self._adjust_container_type(parent, node, annotations)
 
+        if ANN_NULLABLE in annotations:
+            node.nullable = True
+
+        if ANN_OPTIONAL in annotations:
+            node.optional = True
+
         if ANN_ALLOW_NONE in annotations:
             if node.direction == ast.PARAM_DIRECTION_OUT:
                 node.optional = True