[gtk-doc] gtkdoc-mkdb: Add support for (nullable) and (optional) annotations

[Philip Withnall <pwithnall src gnome org>]

commit 36b2f2ba5de7cd4dd1bb6d116361b9b9aaef4f4e
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Mon Jun 23 11:42:34 2014 +0100

    gtkdoc-mkdb: Add support for (nullable) and (optional) annotations
    
    These deprecate and replace (allow-none), which was ill-defined for
    (out) parameters.
    
    This includes some updated unit tests.
    
    Including a wording contribution from Evan Nemerson
    <evan coeus-group com>.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=730777

 gtkdoc-mkdb.in                             |    4 +-
 tests/annotations/docs/tester-sections.txt |    4 ++
 tests/annotations/src/tester.c             |   64 +++++++++++++++++++++++++++-
 tests/annotations/src/tester.h             |    4 ++
 4 files changed, 74 insertions(+), 2 deletions(-)
---
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index c5430d5..e53f136 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -303,7 +303,9 @@ my %AnnotationsUsed;
 my %AnnotationDefinition = (
     # the GObjectIntrospection annotations are defined at:
     # https://live.gnome.org/GObjectIntrospection/Annotations
-    'allow-none' => "NULL is ok, both for passing and for returning.",
+    'allow-none' => "NULL is OK, both for passing and for returning.",
+    'nullable' => "NULL may be passed as the value in, out, in-out; or as a return value.",
+    'optional' => "NULL may be passed instead of a pointer to a location.",
     'array' => "Parameter points to an array of items.",
     'attribute' => "Deprecated free-form custom annotation, replaced by (attributes) annotation.",
     'attributes' => "Free-form key-value pairs.",
diff --git a/tests/annotations/docs/tester-sections.txt b/tests/annotations/docs/tester-sections.txt
index 239ed1d..f540b9e 100644
--- a/tests/annotations/docs/tester-sections.txt
+++ b/tests/annotations/docs/tester-sections.txt
@@ -3,11 +3,15 @@
 <TITLE>GtkdocTester</TITLE>
 GtkdocAnnotation
 annotation_array_length
+annotation_allow_none
 annotation_nullable
 annotation_elementtype
 annotation_elementtype_transfer
 annotation_elementtype_returns
 annotation_outparams
+annotation_outparams_nullable
+annotation_outparams_optional
+annotation_outparams_optional_nullable
 annotation_skip
 annotation_skip_return
 annotation_scope
diff --git a/tests/annotations/src/tester.c b/tests/annotations/src/tester.c
index d731a61..d9d8eba 100644
--- a/tests/annotations/src/tester.c
+++ b/tests/annotations/src/tester.c
@@ -28,7 +28,7 @@ annotation_array_length (GObject *list,
 
 
 /**
- * annotation_nullable:
+ * annotation_allow_none:
  * @uri: a uri
  * @label: (allow-none): an optional string, which is used in ways too
  *  complicated to describe in a single line, making it necessary to wrap it
@@ -39,6 +39,24 @@ annotation_array_length (GObject *list,
  *  free after use, whose description is also rather long
  */
 gchar *
+annotation_allow_none (const gchar *uri,
+                       const gchar *label)
+{
+  return NULL;
+}
+
+/**
+ * annotation_nullable:
+ * @uri: a uri
+ * @label: (nullable): an optional string, which is used in ways too
+ *  complicated to describe in a single line, making it necessary to wrap it
+ *
+ * Document optional parameters.
+ *
+ * Returns: (transfer full) (nullable): Returns stuff which you have to
+ *  free after use, whose description is also rather long
+ */
+gchar *
 annotation_nullable (const gchar *uri,
                      const gchar *label)
 {
@@ -101,6 +119,50 @@ annotation_outparams (GList **list)
 }
 
 /**
+ * annotation_outparams_optional:
+ * @list: (out) (transfer none) (optional): a pointer to take a list, or %NULL
+ *
+ * Document optional parameters.
+ *
+ * Returns: %TRUE for success
+ */
+gboolean
+annotation_outparams_optional (GList **list)
+{
+  return TRUE;
+}
+
+/**
+ * annotation_outparams_nullable:
+ * @list: (out) (transfer none) (nullable): a pointer to take a list; but %NULL
+ * may also be returned
+ *
+ * Document optional parameters.
+ *
+ * Returns: %TRUE for success
+ */
+gboolean
+annotation_outparams_nullable (GList **list)
+{
+  return TRUE;
+}
+
+/**
+ * annotation_outparams_optional_nullable:
+ * @list: (out) (transfer none) (optional) (nullable): a pointer to take a
+ * list, or %NULL; but %NULL may also be returned in @list — isn’t that cool?
+ *
+ * Document optional parameters.
+ *
+ * Returns: %TRUE for success
+ */
+gboolean
+annotation_outparams_optional_nullable (GList **list)
+{
+  return TRUE;
+}
+
+/**
  * annotation_skip: (skip)
  * @list: a pointer to take a list
  *
diff --git a/tests/annotations/src/tester.h b/tests/annotations/src/tester.h
index 612b4d9..677606a 100644
--- a/tests/annotations/src/tester.h
+++ b/tests/annotations/src/tester.h
@@ -16,6 +16,7 @@ struct _GtkdocAnnotation {
 
 void annotation_array_length (GObject *list, gint n_columns, GType *types);
 
+gchar * annotation_allow_none (const gchar *uri, const gchar *label);
 gchar * annotation_nullable (const gchar *uri, const gchar *label);
 
 gboolean annotation_elementtype (const GList *list);
@@ -23,6 +24,9 @@ gboolean annotation_elementtype_transfer (const GList *list);
 GList *annotation_elementtype_returns (void);
 
 gboolean annotation_outparams (GList **list);
+gboolean annotation_outparams_optional (GList **list);
+gboolean annotation_outparams_nullable (GList **list);
+gboolean annotation_outparams_optional_nullable (GList **list);
 
 void annotation_skip (GList *list);
 gboolean annotation_skip_return (GList *list);