fpi-device: Clarify transfer of errors in device complete tasksHEADmaster

2 files changed, 26 insertions, 17 deletions

diff --git a/libfprint/fpi-device.c b/libfprint/fpi-device.c
index 8864fb7..213a6bf 100644
--- a/libfprint/fpi-device.c
+++ b/libfprint/fpi-device.c
@@ -1065,12 +1065,21 @@ fpi_device_task_return_data_free (FpDeviceTaskReturnData *data)
     }
 
   g_object_unref (data->device);
   g_free (data);
 }
 
+/**
+ * fpi_device_return_task_in_idle:
+ * @device: The #FpDevice
+ * @return_type: The #FpDeviceTaskReturnType of @return_data
+ * @return_data: (nullable) (transfer full): The data to return.
+ *
+ * Completes a #FpDevice task in an idle source, stealing the ownership of
+ * the passed @returned_data.
+ */
 static void
 fpi_device_return_task_in_idle (FpDevice              *device,
                                 FpDeviceTaskReturnType return_type,
                                 gpointer               return_data)
 {
   FpDevicePrivate *priv = fp_device_get_instance_private (device);
@@ -1096,13 +1105,13 @@ fpi_device_return_task_in_idle (FpDevice              *device,
 
 /**
  * fpi_device_probe_complete:
  * @device: The #FpDevice
  * @device_id: Unique ID for the device or %NULL
  * @device_name: Human readable name or %NULL for driver name
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing probe operation. If error is %NULL success is assumed.
  */
 void
 fpi_device_probe_complete (FpDevice    *device,
                            const gchar *device_id,
@@ -1142,13 +1151,13 @@ fpi_device_probe_complete (FpDevice    *device,
     }
 }
 
 /**
  * fpi_device_open_complete:
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing open operation. If error is %NULL success is assumed.
  */
 void
 fpi_device_open_complete (FpDevice *device, GError *error)
 {
@@ -1169,13 +1178,13 @@ fpi_device_open_complete (FpDevice *device, GError *error)
     fpi_device_return_task_in_idle (device, FP_DEVICE_TASK_RETURN_ERROR, error);
 }
 
 /**
  * fpi_device_close_complete:
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing close operation. If error is %NULL success is assumed.
  */
 void
 fpi_device_close_complete (FpDevice *device, GError *error)
 {
@@ -1221,13 +1230,13 @@ fpi_device_close_complete (FpDevice *device, GError *error)
 }
 
 /**
  * fpi_device_enroll_complete:
  * @device: The #FpDevice
  * @print: (nullable) (transfer full): The #FpPrint or %NULL on failure
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing enroll operation. The #FpPrint can be stored by the
  * caller for later verification.
  */
 void
 fpi_device_enroll_complete (FpDevice *device, FpPrint *print, GError *error)
@@ -1350,13 +1359,13 @@ fpi_device_verify_complete (FpDevice *device,
     }
 }
 
 /**
  * fpi_device_identify_complete:
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing identify operation.
  *
  * Note that @error should only be set for actual errors. In the case
  * of retry errors, report these using fpi_device_identify_report()
  * and then call this function without any error argument.
@@ -1416,13 +1425,13 @@ fpi_device_identify_complete (FpDevice *device,
 
 
 /**
  * fpi_device_capture_complete:
  * @device: The #FpDevice
  * @image: The #FpImage, or %NULL on error
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing capture operation.
  */
 void
 fpi_device_capture_complete (FpDevice *device,
                              FpImage  *image,
@@ -1463,13 +1472,13 @@ fpi_device_capture_complete (FpDevice *device,
     }
 }
 
 /**
  * fpi_device_delete_complete:
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing delete operation.
  */
 void
 fpi_device_delete_complete (FpDevice *device,
                             GError   *error)
@@ -1492,13 +1501,13 @@ fpi_device_delete_complete (FpDevice *device,
 }
 
 /**
  * fpi_device_list_complete:
  * @device: The #FpDevice
  * @prints: (element-type FpPrint) (transfer container): Possibly empty array of prints or %NULL on error
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing list operation.
  *
  * Please note that the @prints array will be free'ed using
  * g_ptr_array_unref() and the elements are destroyed automatically.
  * As such, you must use g_ptr_array_new_with_free_func() with
@@ -1770,13 +1779,13 @@ fpi_device_suspend_completed (FpDevice *device)
     g_task_return_boolean (task, TRUE);
 }
 
 /**
  * fpi_device_suspend_complete:
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish a suspend request. Only return a %NULL error if suspend has been
  * correctly configured and the current action as returned by
  * fpi_device_get_current_action() will continue to run after resume.
  *
  * In all other cases an error must be returned. Should this happen, the
@@ -1821,13 +1830,13 @@ fpi_device_suspend_complete (FpDevice *device,
   g_cancellable_cancel (priv->current_cancellable);
 }
 
 /**
  * fpi_device_resume_complete:
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish a resume request.
  */
 void
 fpi_device_resume_complete (FpDevice *device,
                             GError   *error)
@@ -1849,13 +1858,13 @@ fpi_device_resume_complete (FpDevice *device,
     g_task_return_boolean (task, TRUE);
 }
 
 /**
  * fpi_device_clear_storage_complete:
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Finish an ongoing clear_storage operation.
  */
 void
 fpi_device_clear_storage_complete (FpDevice *device,
                                    GError   *error)
@@ -1880,13 +1889,13 @@ fpi_device_clear_storage_complete (FpDevice *device,
 /**
 
  * fpi_device_enroll_progress:
  * @device: The #FpDevice
  * @completed_stages: The number of stages that are completed at this point
  * @print: (transfer floating): The #FpPrint for the newly completed stage or %NULL on failure
- * @error: (transfer full): The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Notify about the progress of the enroll operation. This is important for UI interaction.
  * The passed error may be used if a scan needs to be retried, use fpi_device_retry_new().
  */
 void
 fpi_device_enroll_progress (FpDevice *device,
diff --git a/libfprint/fpi-image-device.c b/libfprint/fpi-image-device.c
index 64ea340..8184d3a 100644
--- a/libfprint/fpi-image-device.c
+++ b/libfprint/fpi-image-device.c
@@ -562,13 +562,13 @@ fpi_image_device_retry_scan (FpImageDevice *self, FpDeviceRetry retry)
     }
 }
 
 /**
  * fpi_image_device_session_error:
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: The #GError to report
+ * @error: (nullable) (transfer full): The #GError to report.
  *
  * Report an error while interacting with the device. This effectively
  * aborts the current ongoing action. Note that doing so will result in
  * the deactivation handler to be called and this function must not be
  * used to report an error during deactivation.
  */
@@ -621,13 +621,13 @@ fpi_image_device_session_error (FpImageDevice *self, GError *error)
   fpi_image_device_deactivate (self, TRUE);
 }
 
 /**
  * fpi_image_device_activate_complete:
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: A #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Reports completion of device activation.
  */
 void
 fpi_image_device_activate_complete (FpImageDevice *self, GError *error)
 {
@@ -660,13 +660,13 @@ fpi_image_device_activate_complete (FpImageDevice *self, GError *error)
   fp_image_device_change_state (self, FPI_IMAGE_DEVICE_STATE_AWAIT_FINGER_ON);
 }
 
 /**
  * fpi_image_device_deactivate_complete:
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: A #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Reports completion of device deactivation.
  */
 void
 fpi_image_device_deactivate_complete (FpImageDevice *self, GError *error)
 {
@@ -687,13 +687,13 @@ fpi_image_device_deactivate_complete (FpImageDevice *self, GError *error)
   fp_image_device_maybe_complete_action (self, error);
 }
 
 /**
  * fpi_image_device_open_complete:
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: A #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Reports completion of open operation.
  */
 void
 fpi_image_device_open_complete (FpImageDevice *self, GError *error)
 {
@@ -715,13 +715,13 @@ fpi_image_device_open_complete (FpImageDevice *self, GError *error)
   fpi_device_open_complete (FP_DEVICE (self), error);
 }
 
 /**
  * fpi_image_device_close_complete:
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: A #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
  * Reports completion of close operation.
  */
 void
 fpi_image_device_close_complete (FpImageDevice *self, GError *error)
 {