[gtk-doc] gtkdoc-mkdb: Add support for (nullable) and (optional) annotations
- From: Philip Withnall <pwithnall src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk-doc] gtkdoc-mkdb: Add support for (nullable) and (optional) annotations
- Date: Mon, 23 Jun 2014 11:43:22 +0000 (UTC)
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);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]