GNOME.org
 

[gobject-introspection] Expand on the documentation tests

commit ce4a25dc640bdb02ff30fc233abb1c468721cbbd
Author: Giovanni Campagna <gcampagna src gnome org>
Date:   Tue Aug 28 03:38:46 2012 +0200

    Expand on the documentation tests
    
    Add tests for complex function signatures (including arrays and
    callbacks), for enumerations and for static methods.
    Add JS reference files.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=683046

 .../DocExamples.Callback.page                      |   11 +++
 .../DocExamples.Enum.page                          |   12 ++++
 .../DocExamples.Obj.static_method.page             |   39 ++++++++++++
 .../DocExamples.array_function.page                |   39 ++++++++++++
 .../DocExamples.callback_function.page             |   58 +++++++++++++++++
 .../DocExamples.Callback.page                      |   11 +++
 .../DocExamples.Enum.page                          |   23 +++++++
 .../DocExamples.Obj.static_method.page             |   41 ++++++++++++
 .../DocExamples.array_function.page                |   41 ++++++++++++
 .../DocExamples.callback_function.page             |   54 ++++++++++++++++
 tests/doctool/doc-examples-obj.c                   |   65 ++++++++++++++++++++
 tests/doctool/doc-examples-obj.h                   |   29 +++++++++
 12 files changed, 423 insertions(+), 0 deletions(-)
---
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Callback.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Callback.page
new file mode 100644
index 0000000..22d30c2
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Callback.page
@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<page id="DocExamples.Callback"
+      type="topic"
+      style=""
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+  </info>
+  <title>DocExamples.Callback</title>
+
+</page>
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Enum.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Enum.page
new file mode 100644
index 0000000..56ebc4b
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Enum.page
@@ -0,0 +1,12 @@
+<?xml version="1.0"?>
+<page id="DocExamples.Enum"
+      type="guide"
+      style="enum"
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+    <link type="guide" xref="index"/>
+  </info>
+  <title>DocExamples.Enum</title>
+<p>This is an example to document an enumeration.</p>
+</page>
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page
new file mode 100644
index 0000000..ae7791e
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.Obj.static_method.page
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+
+<page id="DocExamples.Obj.static_method"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:api="http://projectmallard.org/experimental/api/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+    <link type="guide" xref="DocExamples.Obj" group="function"/>
+    <api:function>
+      <api:returns>
+        <api:type>gboolean</api:type>
+      </api:returns>
+      <api:name>doc_examples_obj_static_method</api:name>
+      <api:arg>
+        <api:type>gint*</api:type>
+        <api:name>out_arg</api:name>
+      </api:arg>
+    </api:function>
+  </info>
+  <title>doc_examples_obj_static_method</title>
+<synopsis><code mime="text/x-csrc">
+gboolean doc_examples_obj_static_method (gint* out_arg);
+</code></synopsis>
+<p>This is an example of a function with an out argument
+and a return value.</p>
+
+<table>
+<tr>
+<td><p>out_arg :</p></td>
+<td><p>a pointer to int, or NULL to ignore</p></td>
+</tr>
+<tr>
+<td><p>Returns :</p></td>
+<td><p>TRUE if @out_arg is valid, FALSE otherwise</p></td>
+</tr>
+</table>
+</page>
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.array_function.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.array_function.page
new file mode 100644
index 0000000..a147b6b
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.array_function.page
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+
+<page id="DocExamples.array_function"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:api="http://projectmallard.org/experimental/api/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+    <link type="guide" xref="index" group="function"/>
+    <api:function>
+      <api:returns>
+        <api:type>gint*</api:type>
+      </api:returns>
+      <api:name>doc_examples_array_function</api:name>
+      <api:arg>
+        <api:type>gint*</api:type>
+        <api:name>out_len</api:name>
+      </api:arg>
+    </api:function>
+  </info>
+  <title>doc_examples_array_function</title>
+<synopsis><code mime="text/x-csrc">
+gint* doc_examples_array_function (gint* out_len);
+</code></synopsis>
+<p>This function returns an array with an explicit length,
+and the length should be invisible in most introspected bindings.</p>
+
+<table>
+<tr>
+<td><p>out_len :</p></td>
+<td><p>the length of the returned array</p></td>
+</tr>
+<tr>
+<td><p>Returns :</p></td>
+<td><p>an array of numbers.</p></td>
+</tr>
+</table>
+</page>
diff --git a/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page
new file mode 100644
index 0000000..98958b2
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-C-expected/DocExamples.callback_function.page
@@ -0,0 +1,58 @@
+<?xml version="1.0"?>
+
+<page id="DocExamples.callback_function"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:api="http://projectmallard.org/experimental/api/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+    <link type="guide" xref="index" group="function"/>
+    <api:function>
+      <api:returns>
+        <api:type>void</api:type>
+      </api:returns>
+      <api:name>doc_examples_callback_function</api:name>
+      <api:arg>
+        <api:type>DocExamplesCallback</api:type>
+        <api:name>callback</api:name>
+      </api:arg>
+      <api:arg>
+        <api:type>gpointer</api:type>
+        <api:name>user_data</api:name>
+      </api:arg>
+      <api:arg>
+        <api:type>GDestroyNotify</api:type>
+        <api:name>destroy_notify</api:name>
+      </api:arg>
+    </api:function>
+  </info>
+  <title>doc_examples_callback_function</title>
+<synopsis><code mime="text/x-csrc">
+void doc_examples_callback_function (DocExamplesCallback callback,
+                                     gpointer user_data,
+                                     GDestroyNotify destroy_notify);
+</code></synopsis>
+<p>This is a function that takes a callback. Different languages
+will expose this in different ways (e.g. Python keeps the
+ user_data parameter, while JS doesn't)</p>
+
+<table>
+<tr>
+<td><p>callback :</p></td>
+<td><p>Just Call Me Maybe</p></td>
+</tr>
+<tr>
+<td><p>user_data :</p></td>
+<td><p>your stuff</p></td>
+</tr>
+<tr>
+<td><p>destroy_notify :</p></td>
+<td><p>how to get rid of @user_data</p></td>
+</tr>
+<tr>
+<td><p>Returns :</p></td>
+<td></td>
+</tr>
+</table>
+</page>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Callback.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Callback.page
new file mode 100644
index 0000000..22d30c2
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Callback.page
@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<page id="DocExamples.Callback"
+      type="topic"
+      style=""
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+  </info>
+  <title>DocExamples.Callback</title>
+
+</page>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Enum.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Enum.page
new file mode 100644
index 0000000..0f49606
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Enum.page
@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<page id="DocExamples.Enum"
+      type="guide"
+      style="enum"
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+    <link type="guide" xref="index"/>
+  </info>
+  <title>DocExamples.Enum</title>
+  <p>This is an example to document an enumeration.</p>
+<table>
+<tr>
+<td><p>Enum.FOO :</p></td>
+<td><p>a foo</p></td>
+</tr>
+<tr>
+<td><p>Enum.BAR :</p></td>
+<td><p>a bar</p></td>
+</tr>
+</table>
+
+</page>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page
new file mode 100644
index 0000000..d7990e0
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.Obj.static_method.page
@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+
+<page id="DocExamples.Obj.static_method"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:api="http://projectmallard.org/experimental/api/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+    <link type="guide" xref="DocExamples.Obj" group="function"/>
+    <api:function>
+      <api:returns>
+        <api:type>gboolean</api:type>
+      </api:returns>
+      <api:name>doc_examples_obj_static_method</api:name>
+      <api:arg>
+        <api:type>gint</api:type>
+        <api:name>out_arg</api:name>
+      </api:arg>
+    </api:function>
+  </info>
+  <title>static_method</title>
+<synopsis><code mime="text/x-python">
+ accepts(gint)
+ returns(gboolean)
+def static_method(out_arg)
+</code></synopsis>
+<p>This is an example of a function with an out argument
+and a return value.</p>
+
+<table>
+<tr>
+<td><p>out_arg :</p></td>
+<td><p>a pointer to int, or None to ignore</p></td>
+</tr>
+<tr>
+<td><p>Returns :</p></td>
+<td><p>True if @out_arg is valid, False otherwise</p></td>
+</tr>
+</table>
+</page>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.array_function.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.array_function.page
new file mode 100644
index 0000000..d552e17
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.array_function.page
@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+
+<page id="DocExamples.array_function"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:api="http://projectmallard.org/experimental/api/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+    <link type="guide" xref="index" group="function"/>
+    <api:function>
+      <api:returns>
+        <api:type>[gint]</api:type>
+      </api:returns>
+      <api:name>doc_examples_array_function</api:name>
+      <api:arg>
+        <api:type>gint</api:type>
+        <api:name>out_len</api:name>
+      </api:arg>
+    </api:function>
+  </info>
+  <title>array_function</title>
+<synopsis><code mime="text/x-python">
+ accepts(gint)
+ returns([gint])
+def array_function(out_len)
+</code></synopsis>
+<p>This function returns an array with an explicit length,
+and the length should be invisible in most introspected bindings.</p>
+
+<table>
+<tr>
+<td><p>out_len :</p></td>
+<td><p>the length of the returned array</p></td>
+</tr>
+<tr>
+<td><p>Returns :</p></td>
+<td><p>an array of numbers.</p></td>
+</tr>
+</table>
+</page>
diff --git a/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page
new file mode 100644
index 0000000..ace7645
--- /dev/null
+++ b/tests/doctool/DocExamples-1.0-Python-expected/DocExamples.callback_function.page
@@ -0,0 +1,54 @@
+<?xml version="1.0"?>
+
+<page id="DocExamples.callback_function"
+      type="topic"
+      style="function"
+      xmlns="http://projectmallard.org/1.0/";
+      xmlns:api="http://projectmallard.org/experimental/api/";
+      xmlns:ui="http://projectmallard.org/experimental/ui/";>
+  <info>
+    <link type="guide" xref="index" group="function"/>
+    <api:function>
+      <api:returns>
+        <api:type>none</api:type>
+      </api:returns>
+      <api:name>doc_examples_callback_function</api:name>
+      <api:arg>
+        <api:type>DocExamples.Callback</api:type>
+        <api:name>callback</api:name>
+      </api:arg>
+      <api:arg>
+        <api:type>gpointer</api:type>
+        <api:name>user_data</api:name>
+      </api:arg>
+      <api:arg>
+        <api:type>GLib.DestroyNotify</api:type>
+        <api:name>destroy_notify</api:name>
+      </api:arg>
+    </api:function>
+  </info>
+  <title>callback_function</title>
+<synopsis><code mime="text/x-python">
+ accepts(DocExamples.Callback, gpointer, GLib.DestroyNotify)
+ returns(none)
+def callback_function(callback, user_data, destroy_notify)
+</code></synopsis>
+<p>This is a function that takes a callback. Different languages
+will expose this in different ways (e.g. Python keeps the
+ user_data parameter, while JS doesn't)</p>
+
+<table>
+<tr>
+<td><p>callback :</p></td>
+<td><p>Just Call Me Maybe</p></td>
+</tr>
+<tr>
+<td><p>user_data :</p></td>
+<td><p>your stuff</p></td>
+</tr>
+<tr>
+<td><p>destroy_notify :</p></td>
+<td><p>how to get rid of @user_data</p></td>
+</tr>
+</table>
+</page>
diff --git a/tests/doctool/doc-examples-obj.c b/tests/doctool/doc-examples-obj.c
index 44360d9..992e715 100644
--- a/tests/doctool/doc-examples-obj.c
+++ b/tests/doctool/doc-examples-obj.c
@@ -125,3 +125,68 @@ doc_examples_obj_method (DocExamplesObj *self, gint first_arg, gfloat second_arg
 {
   return FALSE;
 }
+
+/**
+ * doc_examples_obj_static_method:
+ * @out_arg: (out) (allow-none): a pointer to int, or %NULL to ignore
+ *
+ * This is an example of a function with an out argument
+ * and a return value.
+ *
+ * Returns: %TRUE if @out_arg is valid, %FALSE otherwise
+ */
+gboolean
+doc_examples_obj_static_method (gint *out_arg)
+{
+  if (out_arg)
+    *out_arg = 42;
+
+  return TRUE;
+}
+
+/**
+ * doc_examples_array_function:
+ * @out_len: (out): the length of the returned array
+ *
+ * This function returns an array with an explicit length,
+ * and the length should be invisible in most introspected bindings.
+ *
+ * Returns: (array length=out_len) (transfer full): an array of numbers.
+ */
+gint *
+doc_examples_array_function (gint *out_len)
+{
+  gint *array;
+  int i, n = 3;
+
+  array = g_new(int, n);
+  for (i = 0; i < n; i++)
+    array[i] = i;
+
+  *out_len = n;
+  return array;
+}
+
+/**
+ * doc_examples_callback_function:
+ * @callback: Just Call Me Maybe
+ * @user_data: your stuff
+ * @destroy_notify: how to get rid of @user_data
+ *
+ * This is a function that takes a callback. Different languages
+ * will expose this in different ways (e.g. Python keeps the
+ * @user_data parameter, while JS doesn't)
+ */
+void
+doc_examples_callback_function (DocExamplesCallback callback,
+                                gpointer            user_data,
+                                GDestroyNotify      destroy_notify)
+{
+  gchar *result;
+
+  result = callback (42, 17);
+  g_free (result);
+
+  if (user_data && destroy_notify)
+    destroy_notify (user_data);
+}
diff --git a/tests/doctool/doc-examples-obj.h b/tests/doctool/doc-examples-obj.h
index c8840d7..e7aba55 100644
--- a/tests/doctool/doc-examples-obj.h
+++ b/tests/doctool/doc-examples-obj.h
@@ -59,6 +59,35 @@ DocExamplesObj *doc_examples_obj_new (void);
 gboolean doc_examples_obj_method (DocExamplesObj *self, gint first_arg, gfloat second_arg,
                                   gboolean boolean_arg, gpointer pointer_arg, gchar *string);
 
+gboolean doc_examples_obj_static_method (gint *out_arg);
+
+gint *doc_examples_array_function (gint *out_len);
+
+/**
+ * DocExamplesEnum:
+ * @DOC_EXAMPLES_FOO: a foo
+ * @DOC_EXAMPLES_BAR: a bar
+ *
+ * This is an example to document an enumeration.
+ */
+typedef enum {
+  DOC_EXAMPLES_FOO,
+  DOC_EXAMPLES_BAR
+} DocExamplesEnum;
+
+/**
+ * DocExamplesCallback:
+ * @one: first parameter
+ * @two: second parameter
+ *
+ * Returns: something
+ */
+typedef gchar * (*DocExamplesCallback) (int one, int two);
+
+void doc_examples_callback_function (DocExamplesCallback callback,
+                                     gpointer            user_data,
+                                     GDestroyNotify      destroy_notify);
+
 G_END_DECLS
 
 #endif /* _DOC_EXAMPLES_OBJ_H */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]