[Libguestfs] [PATCH 08/16] gobject: Add basic gtk-doc for all parameters

[Matthew Booth]

---
 generator/generator_gobject.ml |   20 ++++++++++++++++----
 1 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/generator/generator_gobject.ml b/generator/generator_gobject.ml
index 017e860..8516e1f 100644
--- a/generator/generator_gobject.ml
+++ b/generator/generator_gobject.ml
@@ -370,6 +370,8 @@ guestfs_session_new(void)
 
 /**
  * guestfs_session_close:
+ * @session: (transfer none): A GuestfsSession object
+ * @err: A GError object to receive any generated errors
  *
  * Close a libguestfs session.
  *
@@ -641,12 +643,16 @@ let generate_gobject_c_methods () =
         "NULL" (* NULL is a valid return for RConstOptString. Error is
                   indicated by also setting *err to a non-NULL value *)
       in
+      let cancellable =
+        List.exists (function Cancellable -> true | _ -> false) flags
+      in
 
       (* The comment header, including GI annotations for arguments and the
       return value *)
 
       pr "/**\n";
       pr " * guestfs_session_%s:\n" name;
+      pr " * @session: (transfer none): A GuestfsSession object\n";
 
       List.iter (
         fun argt ->
@@ -669,7 +675,8 @@ let generate_gobject_c_methods () =
           | DeviceList _ ->
             pr " (transfer none) (array zero-terminated=1) (element-type filename): an array of strings"
           | BufferIn n ->
-            pr " (transfer none) (array length=%s_size) (element-type guint8): an array of binary data" n
+            pr " (transfer none) (array length=%s_size) (element-type guint8): an array of binary data\n" n;
+            pr " * @%s_size: The size of %s, in bytes" n n;
           | Pointer _ ->
             failwith "gobject bindings do not support Pointer arguments"
           );
@@ -677,6 +684,14 @@ let generate_gobject_c_methods () =
       ) args;
       if optargs <> [] then
         pr " * @optargs: (transfer none) (allow-none): a %s containing optional arguments\n" camel_name;
+      (match ret with
+      | RBufferOut _ ->
+        pr " * @size_r: The size of the returned buffer, in bytes\n";
+      | _ -> ());
+      if cancellable then (
+        pr " * @cancellable: A GCancellable object\n";
+      );
+      pr " * @err: A GError object to receive any generated errors\n";
       pr " *\n";
 
       pr " * %s\n" shortdesc;
@@ -716,9 +731,6 @@ let generate_gobject_c_methods () =
       generate_gobject_proto ~single_line:false name style flags;
       pr "\n{\n";
 
-      let cancellable =
-        List.exists (function Cancellable -> true | _ -> false) flags
-      in
       if cancellable then (
         pr "  /* Check we haven't already been cancelled */\n";
         pr "  if (g_cancellable_set_error_if_cancelled (cancellable, err))\n";
-- 
1.7.7.6