introspection: Add Graphene-1.0 as dependency and enhance documentation

Add (transfer) annotation when required and enhance the (element-type) and (array) coverage.

Signed-off-by: Corentin Noël <corentin.noel@collabora.com>

src/gxr-action-set.c

@@ -79,6 +79,17 @@ gxr_action_sets_poll (GxrActionSet **sets, uint32_t count)
   return TRUE;
 }
 
+/**
+ * gxr_action_set_connect_digital_from_float:
+ * @self: a #GxrActionSet
+ * @context: a #GxrContext
+ * @threshold: a threshold
+ * @haptic_url: the haptic url
+ * @callback: (scope async): a #GCallback
+ * @data: user data passed to the @callback
+ *
+ * Returns: (transfer full): a new #GxrAction
+ */
 GxrAction *
 gxr_action_set_connect_digital_from_float (GxrActionSet *self,
                                            GxrContext   *context,
@@ -124,6 +135,17 @@ gxr_action_set_connect_digital_from_float (GxrActionSet *self,
   return action;
 }
 
+/**
+ * gxr_action_set_connect:
+ * @self: a #GxrActionSet
+ * @context: a #GxrContext
+ * @type: a #GxrActionType
+ * @url: an url
+ * @callback: (scope async): a #GCallback
+ * @data: user data passed to the @callback
+ *
+ * Returns: %TRUE on success
+ */
 gboolean
 gxr_action_set_connect (GxrActionSet *self,
                         GxrContext   *context,
@@ -170,7 +192,12 @@ gxr_action_set_connect (GxrActionSet *self,
   return TRUE;
 }
 
-
+/**
+ * gxr_action_set_get_actions:
+ * @self: a #GxrActionSet
+ *
+ * Returns: (transfer none) (element-type GxrAction): a list of #GxrAction
+ */
 GSList *
 gxr_action_set_get_actions (GxrActionSet *self)
 {

src/gxr-action.c

@@ -131,6 +131,12 @@ gxr_action_get_action_type (GxrAction *self)
   return priv->type;
 }
 
+/**
+ * gxr_action_get_action_set:
+ * @self: a #GxrAction
+ *
+ * Returns: (transfer none): the #GxrActionSet
+ */
 GxrActionSet *
 gxr_action_get_action_set (GxrAction *self)
 {
@@ -138,6 +144,12 @@ gxr_action_get_action_set (GxrAction *self)
   return priv->action_set;
 }
 
+/**
+ * gxr_action_get_url:
+ * @self: a #GxrAction
+ *
+ * Returns: (transfer none): the url
+ */
 gchar*
 gxr_action_get_url (GxrAction *self)
 {
@@ -152,6 +164,12 @@ gxr_action_set_action_type (GxrAction *self, GxrActionType type)
   priv->type = type;
 }
 
+/**
+ * gxr_action_set_action_set:
+ * @self: a #GxrAction
+ * @action_set: (transfer full): a #GxrActionSet
+ *
+ */
 void
 gxr_action_set_action_set (GxrAction *self, GxrActionSet *action_set)
 {
@@ -159,6 +177,12 @@ gxr_action_set_action_set (GxrAction *self, GxrActionSet *action_set)
   priv->action_set = action_set;
 }
 
+/**
+ * gxr_action_set_url:
+ * @self: a #GxrAction
+ * @url: (transfer full): the url
+ *
+ */
 void
 gxr_action_set_url (GxrAction *self, gchar* url)
 {

src/gxr-context.c

@@ -230,6 +230,16 @@ GxrContext *gxr_context_new (GxrAppType type,
                                    app_name, app_version);
 }
 
+/**
+ * gxr_context_new_from_vulkan_extensions:
+ * @type: a #GxrAppType
+ * @instance_ext_list: (element-type utf8): a list of instance extensions
+ * @device_ext_list: (element-type utf8): a list of device extensions
+ * @app_name: the application name
+ * @app_version: the application version
+ *
+ * Returns: (transfer full): a new #GxrContext
+ */
 GxrContext *gxr_context_new_from_vulkan_extensions (GxrAppType type,
                                                     GSList *instance_ext_list,
                                                     GSList *device_ext_list,
@@ -241,6 +251,17 @@ GxrContext *gxr_context_new_from_vulkan_extensions (GxrAppType type,
                                app_name, app_version);
 }
 
+/**
+ * gxr_context_new_full:
+ * @type: a #GxrAppType
+ * @api: a #GxrApi
+ * @instance_ext_list: (element-type utf8): a list of instance extensions
+ * @device_ext_list: (element-type utf8): a list of device extensions
+ * @app_name: the application name
+ * @app_version: the application version
+ *
+ * Returns: (transfer full): a new #GxrContext
+ */
 GxrContext *gxr_context_new_full (GxrAppType type,
                                   GxrApi     api,
                                   GSList    *instance_ext_list,
@@ -328,6 +349,12 @@ gxr_context_get_api (GxrContext *self)
   return priv->api;
 }
 
+/**
+ * gxr_context_get_gulkan:
+ * @self: a #GxrContext
+ *
+ * Returns: (transfer none): a #GulkanClient
+ */
 GulkanClient*
 gxr_context_get_gulkan (GxrContext *self)
 {
@@ -351,6 +378,16 @@ gxr_context_get_head_pose (GxrContext *self, graphene_matrix_t *pose)
   return klass->get_head_pose (self, pose);
 }
 
+/**
+ * gxr_context_get_frustum_angles:
+ * @self: a #GxrContext
+ * @eye: a #GxrEye
+ * @left: (out): The angle from the center view axis to the left in deg.
+ * @right: (out): The angle from the center view axis to the right in deg.
+ * @top: (out): The angle from the center view axis to the top in deg.
+ * @bottom: (out): The angle from the center view axis to the bottom in deg.
+ *
+ */
 void
 gxr_context_get_frustum_angles (GxrContext *self, GxrEye eye,
                                 float *left, float *right,
@@ -543,12 +580,19 @@ gxr_context_end_frame (GxrContext *self)
   return res;
 }
 
+/**
+ * gxr_context_new_action_set_from_url:
+ * @self: a #GxrContext
+ * @url: an url
+ *
+ * Returns: (transfer full) (nullable): a #GxrActionSet
+ */
 GxrActionSet *
 gxr_context_new_action_set_from_url (GxrContext *self, gchar *url)
 {
   GxrContextClass *klass = GXR_CONTEXT_GET_CLASS (self);
   if (klass->new_action_set_from_url == NULL)
-    return FALSE;
+    return NULL;
   return klass->new_action_set_from_url (self, url);
 }
 
@@ -655,7 +699,7 @@ gxr_context_new_action_from_type_url (GxrContext   *self,
 {
   GxrContextClass *klass = GXR_CONTEXT_GET_CLASS (self);
   if (klass->new_action_from_type_url == NULL)
-    return FALSE;
+    return NULL;
   return klass->new_action_from_type_url (self, action_set, type, url);
 }
 
@@ -664,20 +708,32 @@ gxr_context_new_overlay (GxrContext *self, gchar* key)
 {
   GxrContextClass *klass = GXR_CONTEXT_GET_CLASS (self);
   if (klass->new_overlay == NULL)
-    return FALSE;
+    return NULL;
   return klass->new_overlay (self, key);
 }
 
+/**
+ * gxr_context_get_model_list:
+ * @self: a #GxrContext
+ *
+ * Returns: (transfer full) (element-type utf8): a list of models
+ */
 GSList *
 gxr_context_get_model_list (GxrContext *self)
 {
   GxrContextClass *klass = GXR_CONTEXT_GET_CLASS (self);
   if (klass->get_model_list == NULL)
-    return FALSE;
+    return NULL;
   return klass->get_model_list (self);
 }
 
-
+/**
+ * gxr_context_get_instance_extensions:
+ * @self: a #GxrContext
+ * @out_list: (out) (element-type utf8): a list of instance extensions
+ *
+ * Returns: %TRUE on success
+ */
 gboolean
 gxr_context_get_instance_extensions (GxrContext *self, GSList **out_list)
 {
@@ -687,6 +743,13 @@ gxr_context_get_instance_extensions (GxrContext *self, GSList **out_list)
   return klass->get_instance_extensions (self, out_list);
 }
 
+/**
+ * gxr_context_get_device_extensions:
+ * @self: a #GxrContext
+ * @out_list: (out) (element-type utf8): a list of device extensions
+ *
+ * Returns: %TRUE on success
+ */
 gboolean
 gxr_context_get_device_extensions (GxrContext   *self,
                                    GulkanClient *gc,
@@ -698,6 +761,12 @@ gxr_context_get_device_extensions (GxrContext   *self,
   return klass->get_device_extensions (self, gc, out_list);
 }
 
+/**
+ * gxr_context_get_device_manager:
+ * @self: a #GxrContext
+ *
+ * Returns: (transfer none): a #GxrDeviceManager
+ */
 GxrDeviceManager *
 gxr_context_get_device_manager (GxrContext *self)
 {
@@ -710,15 +779,21 @@ gxr_context_get_view_count (GxrContext *self)
 {
   GxrContextClass *klass = GXR_CONTEXT_GET_CLASS (self);
   if (klass->get_view_count == NULL)
-    return FALSE;
+    return 0;
   return klass->get_view_count (self);
 }
 
+/**
+ * gxr_context_get_acquired_framebuffer:
+ * @self: a #GxrContext
+ *
+ * Returns: (transfer none): a #GulkanFrameBuffer
+ */
 GulkanFrameBuffer *
 gxr_context_get_acquired_framebuffer (GxrContext *self, uint32_t view)
 {
   GxrContextClass *klass = GXR_CONTEXT_GET_CLASS (self);
   if (klass->get_acquired_framebuffer == NULL)
-    return FALSE;
+    return NULL;
   return klass->get_acquired_framebuffer (self, view);
 }

src/gxr-controller.c

@@ -99,36 +99,72 @@ gxr_controller_finalize (GObject *gobject)
   G_OBJECT_CLASS (gxr_controller_parent_class)->finalize (gobject);
 }
 
+/**
+ * gxr_controller_get_pointer:
+ * @self: a #GxrController
+ *
+ * Returns: (transfer none): a #GxrPointer
+ */
 GxrPointer *
 gxr_controller_get_pointer (GxrController *self)
 {
   return self->pointer_ray;
 }
 
+/**
+ * gxr_controller_get_pointer_tip:
+ * @self: a #GxrController
+ *
+ * Returns: (transfer none): a #GxrPointerTip
+ */
 GxrPointerTip *
 gxr_controller_get_pointer_tip (GxrController *self)
 {
   return self->pointer_tip;
 }
 
+/**
+ * gxr_controller_set_pointer:
+ * @self: a #GxrController
+ * @pointer: (transfer full): a #GxrPointer
+ *
+ */
 void
 gxr_controller_set_pointer (GxrController *self, GxrPointer *pointer)
 {
   self->pointer_ray = pointer;
 }
 
+/**
+ * gxr_controller_set_pointer_tip:
+ * @self: a #GxrController
+ * @tip: (transfer full): a #GxrPointerTip
+ *
+ */
 void
 gxr_controller_set_pointer_tip (GxrController *self, GxrPointerTip *tip)
 {
   self->pointer_tip = tip;
 }
 
+/**
+ * gxr_controller_get_hover_state:
+ * @self: a #GxrController
+ *
+ * Returns: (transfer none): a #GxrHoverState
+ */
 GxrHoverState *
 gxr_controller_get_hover_state (GxrController *self)
 {
   return &self->hover_state;
 }
 
+/**
+ * gxr_controller_get_grab_state:
+ * @self: a #GxrController
+ *
+ * Returns: (transfer none): a #GxrGrabState
+ */
 GxrGrabState *
 gxr_controller_get_grab_state (GxrController *self)
 {

src/gxr-device-manager.c

@@ -104,6 +104,12 @@ gxr_device_manager_emit_device_deactivate (GxrDeviceManager *self,
   g_signal_emit (self, dm_signals[DEVICE_DEACTIVATE_EVENT], 0, event);
 }
 
+/**
+ * gxr_device_manager_get_controllers:
+ * @self: a #GxrDeviceManager
+ *
+ * Returns: (transfer none) (element-type GxrDevice): a list of #GxrDevice
+ */
 GSList *
 gxr_device_manager_get_controllers (GxrDeviceManager *self)
 {
@@ -218,6 +224,13 @@ gxr_device_manager_update_poses (GxrDeviceManager *self, GxrPose *poses)
   g_mutex_unlock (&self->device_mutex);
 }
 
+/**
+ * gxr_device_manager_get:
+ * @self: a #GxrDeviceManager
+ * @device_id: the device id
+ *
+ * Returns: (transfer none) : a #GxrDevice
+ */
 GxrDevice *
 gxr_device_manager_get (GxrDeviceManager *self, guint64 device_id)
 {
@@ -230,6 +243,12 @@ gxr_device_manager_get (GxrDeviceManager *self, guint64 device_id)
   return d;
 }
 
+/**
+ * gxr_device_manager_get_devices:
+ * @self: a #GxrDeviceManager
+ *
+ * Returns: (transfer none) (element-type GxrDevice): a list of #GxrDevice
+ */
 GList *
 gxr_device_manager_get_devices (GxrDeviceManager *self)
 {

src/gxr-manifest.c

@@ -449,6 +449,12 @@ gxr_manifest_load_bindings (GxrManifest *self, const char *resource_path)
   return TRUE;
 }
 
+/**
+ * gxr_manifest_get_binding_filenames:
+ * @self: a #GxrManifest
+ *
+ * Returns: (transfer none) (element-type utf8): a list of file names
+ */
 GSList *
 gxr_manifest_get_binding_filenames (GxrManifest *self)
 {
@@ -461,6 +467,12 @@ gxr_manifest_new (void)
   return (GxrManifest *) g_object_new (GXR_TYPE_MANIFEST, 0);
 }
 
+/**
+ * gxr_manifest_get_binding_manifests:
+ * @self: a #GxrManifest
+ *
+ * Returns: (transfer none) (element-type GxrBindingManifest): a list of #GxrBindingManifest
+ */
 GSList *
 gxr_manifest_get_binding_manifests (GxrManifest *self)
 {

src/gxr-manifest.h

@@ -125,7 +125,7 @@ gxr_manifest_get_binding_filenames (GxrManifest *self);
 
 /* GxrBindingManifest */
 GSList *
-gxr_manifest_get_binding_manifests (GxrManifest *manifest);
+gxr_manifest_get_binding_manifests (GxrManifest *self);
 
 G_END_DECLS
 

src/gxr-overlay.c

@@ -512,6 +512,12 @@ gxr_overlay_print_info (GxrOverlay *self)
   return klass->print_info (self);
 }
 
+/**
+ * gxr_overlay_get_context:
+ * @self: a #GxrOverlay
+ *
+ * Returns: (transfer none): a #GxrContext
+ */
 GxrContext *
 gxr_overlay_get_context (GxrOverlay *self)
 {

src/gxr-pointer-tip.c

@@ -121,6 +121,12 @@ gxr_pointer_tip_set_and_submit_texture (GxrPointerTip *self,
   iface->set_and_submit_texture (self, texture);
 }
 
+/**
+ * gxr_pointer_tip_get_texture:
+ * @self: a #GxrPointerTip
+ *
+ * Returns: (transfer none): a #GulkanTexture
+ */
 GulkanTexture *
 gxr_pointer_tip_get_texture (GxrPointerTip *self)
 {
@@ -128,6 +134,12 @@ gxr_pointer_tip_get_texture (GxrPointerTip *self)
   return iface->get_texture (self);
 }
 
+/**
+ * gxr_pointer_tip_get_data:
+ * @self: a #GxrPointerTip
+ *
+ * Returns: (transfer none): a #GxrPointerTipData
+ */
 GxrPointerTipData*
 gxr_pointer_tip_get_data (GxrPointerTip *self)
 {
@@ -135,6 +147,12 @@ gxr_pointer_tip_get_data (GxrPointerTip *self)
   return iface->get_data (self);
 }
 
+/**
+ * gxr_pointer_tip_get_gulkan_client:
+ * @self: a #GxrPointerTip
+ *
+ * Returns: (transfer none): a #GulkanClient
+ */
 GulkanClient*
 gxr_pointer_tip_get_gulkan_client (GxrPointerTip *self)
 {
@@ -273,10 +291,17 @@ _render_cairo (int                 w,
   return pixbuf;
 }
 
-/** _render:
+/**
+ * gxr_pointer_tip_render:
+ * @self: a #GxrPointerTip
+ * @progress: the pulse progress
+ *
  * Renders the pointer tip with the desired colors.
  * If background scale is > 1, a transparent white background circle is rendered
- * behind the pointer tip. */
+ * behind the pointer tip.
+ *
+ * Returns: (transfer full) (nullable): a new #GdkPixbuf
+ */
 GdkPixbuf*
 gxr_pointer_tip_render (GxrPointerTip *self,
                         float          progress)

src/gxr-pointer.c

@@ -54,6 +54,12 @@ gxr_pointer_reset_length (GxrPointer *self)
   gxr_pointer_set_length (self, data->default_length);
 }
 
+/**
+ * gxr_pointer_get_data:
+ * @self: a #GxrPointer
+ *
+ * Returns: (transfer none): a #GxrPointerData
+ */
 GxrPointerData*
 gxr_pointer_get_data (GxrPointer *self)
 {

src/meson.build

@@ -170,7 +170,7 @@ if get_option('introspection')
     identifier_prefix: 'Gxr',
     symbol_prefix: 'gxr',
     export_packages: api_path,
-    includes: [ 'cairo-1.0', 'GdkPixbuf-2.0', 'Gdk-3.0'],
+    includes: [ 'cairo-1.0', 'GdkPixbuf-2.0', 'Gdk-3.0', 'Graphene-1.0', 'Gulkan-'+api_version],
     header: 'gxr/gxr.h',
     install: true,
   )