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
@@ -1070,2 +1070,11 @@ fpi_device_task_return_data_free (FpDeviceTaskReturnData *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
@@ -1101,3 +1110,3 @@ fpi_device_return_task_in_idle (FpDevice              *device,
  * @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
  *
@@ -1147,3 +1156,3 @@ fpi_device_probe_complete (FpDevice    *device,
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -1174,3 +1183,3 @@ fpi_device_open_complete (FpDevice *device, GError *error)
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -1226,3 +1235,3 @@ fpi_device_close_complete (FpDevice *device, GError *error)
  * @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
  *
@@ -1355,3 +1364,3 @@ fpi_device_verify_complete (FpDevice *device,
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -1421,3 +1430,3 @@ fpi_device_identify_complete (FpDevice *device,
  * @image: The #FpImage, or %NULL on error
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -1468,3 +1477,3 @@ fpi_device_capture_complete (FpDevice *device,
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -1497,3 +1506,3 @@ fpi_device_delete_complete (FpDevice *device,
  * @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
  *
@@ -1775,3 +1784,3 @@ fpi_device_suspend_completed (FpDevice *device)
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -1826,3 +1835,3 @@ fpi_device_suspend_complete (FpDevice *device,
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -1854,3 +1863,3 @@ fpi_device_resume_complete (FpDevice *device,
  * @device: The #FpDevice
- * @error: The #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -1885,3 +1894,3 @@ fpi_device_clear_storage_complete (FpDevice *device,
  * @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
  *
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
@@ -567,3 +567,3 @@ fpi_image_device_retry_scan (FpImageDevice *self, FpDeviceRetry retry)
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: The #GError to report
+ * @error: (nullable) (transfer full): The #GError to report.
  *
@@ -626,3 +626,3 @@ fpi_image_device_session_error (FpImageDevice *self, GError *error)
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: A #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -665,3 +665,3 @@ fpi_image_device_activate_complete (FpImageDevice *self, GError *error)
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: A #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -692,3 +692,3 @@ fpi_image_device_deactivate_complete (FpImageDevice *self, GError *error)
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: A #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *
@@ -720,3 +720,3 @@ fpi_image_device_open_complete (FpImageDevice *self, GError *error)
  * @self: a #FpImageDevice imaging fingerprint device
- * @error: A #GError or %NULL on success
+ * @error: (nullable) (transfer full): The #GError or %NULL on success
  *