Fix docstring differences between API files and C implementations

Fix various docstring inconsistencies found by comparing .api files
with their corresponding C implementation files:
- crypto: fix swapped keyfile_offset/key_size descriptions, update URL
- dm: fix stray parentheses, add error handling note to API
- loop: add NULL return case to API
- btrfs: fix stray parenthesis in C
- lvm: fix copy-paste error in vdo_disable_deduplication docstring name,
  fix vdo_info parameter name in lvm-dbus.c
- mdraid: add NULL return cases to API
- part: fix swapped tech categories for set_part_name/set_part_uuid
- s390: sync parameter descriptions, fix online/offline typo in
  zfcp_scsi_offline description
- nvdimm: fix parameter names in API, add tech category, add mode examples
- fs: fix unmount tech category, complete truncated @extra descriptions
- nvme: fix sanitize docstring saying "format command"

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vojtechtrefny

src/lib/plugin_apis/crypto.api

@@ -855,8 +855,8 @@ BDCryptoKeyslotContext* bd_crypto_keyslot_context_new_passphrase (const guint8 *
 /**
  * bd_crypto_keyslot_context_new_keyfile:
  * @keyfile: a key file for the new context
- * @keyfile_offset: number of bytes to read from @keyfile or 0 for unlimited
- * @key_size: number of bytes to skip at start of @keyfile
+ * @keyfile_offset: number of bytes to skip at start of @keyfile
+ * @key_size: number of bytes to read from @keyfile or 0 for unlimited
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns (transfer full): new %BDCryptoKeyslotContext initialized by key file or
@@ -1299,7 +1299,7 @@ gboolean bd_crypto_keyring_add_key (const gchar *key_desc, const guint8 *key_dat
  * To achieve this, we calculate the chi square value of the first
  * 512 Bytes and treat devices with a chi square value between 136
  * and 426 as candidates for being encrypted.
- * For the reasoning, see: https://tails.boum.org/blueprint/veracrypt/
+ * For the reasoning, see: https://gitlab.tails.boum.org/tails/blueprints/-/wikis/veracrypt/#detecting-veracrypt-volumes
  *
  * Returns: %TRUE if the given @device seems to be encrypted or %FALSE if not or
  * failed to determine (the @error) is populated with the error in such

src/lib/plugin_apis/dm.api

@@ -110,7 +110,8 @@ gchar* bd_dm_get_subsystem_from_name (const gchar *device_name, GError **error);
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns: whether the given @map_name exists (and is live if @live_only is
- * %TRUE (and is active if @active_only is %TRUE)).
+ * %TRUE (and is active if @active_only is %TRUE)). If %FALSE is returned,
+ * @error indicates whether error appeared (non-%NULL) or not (%NULL).
  *
  * Tech category: %BD_DM_TECH_MAP-%BD_DM_TECH_MODE_QUERY
  */

src/lib/plugin_apis/fs.api

@@ -919,6 +919,7 @@ gboolean bd_fs_unfreeze (const gchar *mountpoint, GError **error);
  *                                               uid (gid), if you specify one of
  *                                               these, the function will run in
  *                                               a child process with real user
+ *                                               and/or group ID set to these values.
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns: whether @spec was successfully unmounted or not
@@ -942,6 +943,7 @@ gboolean bd_fs_unmount (const gchar *spec, gboolean lazy, gboolean force, const
  *                                               uid (gid), if you specify one of
  *                                               these, the function will run in
  *                                               a child process with real user
+ *                                               and/or group ID set to these values.
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns: whether @device (or @mountpoint) was successfully mounted or not

src/lib/plugin_apis/loop.api

@@ -122,7 +122,8 @@ BDLoopInfo* bd_loop_info (const gchar *loop, GError **error);
  * @file: path of the backing file to get loop name for
  * @error: (out) (optional): place to store error (if any)
  *
- * Returns: (transfer full): name of the loop device associated with the given @file
+ * Returns: (transfer full): name of the loop device associated with the given
+ * @file or %NULL if failed to determine
  *
  * Tech category: %BD_LOOP_TECH_LOOP-%BD_LOOP_TECH_MODE_QUERY
  */

src/lib/plugin_apis/mdraid.api

@@ -416,7 +416,7 @@ BDMDDetailData* bd_md_detail (const gchar *raid_spec, GError **error);
  * @uuid: UUID to canonicalize
  * @error: (out) (optional): place to store error (if any)
  *
- * Returns: (transfer full): canonicalized form of @uuid
+ * Returns: (transfer full): canonicalized form of @uuid or %NULL in case of error
  *
  * This function expects a UUID in the form that mdadm returns. The change is as
  * follows: 3386ff85:f5012621:4a435f06:1eb47236 -> 3386ff85-f501-2621-4a43-5f061eb47236
@@ -430,7 +430,7 @@ gchar* bd_md_canonicalize_uuid (const gchar *uuid, GError **error);
  * @uuid: UUID to transform into format used by MD RAID
  * @error: (out) (optional): place to store error (if any)
  *
- * Returns: (transfer full): transformed form of @uuid
+ * Returns: (transfer full): transformed form of @uuid or %NULL in case of error
  *
  * This function expects a UUID in the canonical (traditional format) and
  * returns a UUID in the format used by MD RAID and is thus reverse to

src/lib/plugin_apis/nvdimm.api

@@ -214,12 +214,11 @@ BDNVDIMMNamespaceInfo* bd_nvdimm_namespace_info (const gchar *namespace, const B
 /**
  * bd_nvdimm_list_namespaces:
  * @bus: (nullable): return only namespaces on given bus (specified by name),
- *                     %NULL may be specified to return namespaces from all buses
- * @region: (nullable): return only namespaces on given region (specified by regionX name or region id),
+ *                    %NULL may be specified to return namespaces from all buses
+ * @region: (nullable): return only namespaces on given region (specified by 'regionX' name),
  *                        %NULL may be specified to return namespaces from all regions
  * @idle: whether to list idle (not enabled) namespaces too
- * @extra: (nullable) (array zero-terminated=1): extra options for the creation (right now
- *                                                 passed to the 'ndctl' utility)
+ * @extra: (nullable) (array zero-terminated=1): extra options (currently unused)
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns: (array zero-terminated=1): information about the namespaces on @bus and @region or
@@ -242,6 +241,8 @@ BDNVDIMMNamespaceInfo** bd_nvdimm_list_namespaces (const gchar *bus, const gchar
  *
  * Returns: whether @namespace was successfully reconfigured or not
  *
+ * Tech category: %BD_NVDIMM_TECH_NAMESPACE-%BD_NVDIMM_TECH_MODE_RECONFIGURE
+ *
  * Deprecated: 3.1: NVDIMM plugin will be removed in the next major release
  */
 gboolean bd_nvdimm_namespace_reconfigure (const gchar* namespace, BDNVDIMMNamespaceMode mode, gboolean force, const BDExtraArg **extra, GError** error);

src/lib/plugin_apis/nvme.api

@@ -1193,7 +1193,7 @@ gboolean bd_nvme_format (const gchar *device, guint16 lba_data_size, guint16 met
  * The sanitize operation is set to run under the Allow Unrestricted Sanitize Exit
  * mode.
  *
- * Returns: %TRUE if the format command finished successfully, %FALSE otherwise with @error set.
+ * Returns: %TRUE if the sanitize command finished successfully, %FALSE otherwise with @error set.
  *
  * Tech category: %BD_NVME_TECH_NVME-%BD_NVME_TECH_MODE_MANAGE
  */

src/lib/plugin_apis/part.api

@@ -385,7 +385,7 @@ gboolean bd_part_set_part_id (const gchar *disk, const gchar *part, const gchar
  *
  * Returns: whether the @uuid type was successfully set for @part or not
  *
- * Tech category: %BD_PART_TECH_MODE_MODIFY_PART + the tech according to the partition table type
+ * Tech category: %BD_PART_TECH_GPT-%BD_PART_TECH_MODE_MODIFY_PART
  */
 gboolean bd_part_set_part_uuid (const gchar *disk, const gchar *part, const gchar *uuid, GError **error);
 

src/lib/plugin_apis/s390.api

@@ -53,7 +53,7 @@ gboolean bd_s390_dasd_format (const gchar *dasd, const BDExtraArg **extra, GErro
 
 /**
  * bd_s390_dasd_needs_format:
- * @dasd: dasd to check, whether it needs dasdfmt run on it
+ * @dasd: dasd to check, given as device number
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns: whether a dasd needs dasdfmt run against it
@@ -64,7 +64,7 @@ gboolean bd_s390_dasd_needs_format (const gchar *dasd, GError **error);
 
 /**
  * bd_s390_dasd_online:
- * @dasd: dasd to switch online
+ * @dasd: dasd to switch online, given as device number
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns: whether a dasd was successfully switched online
@@ -130,9 +130,9 @@ gchar* bd_s390_zfcp_sanitize_lun_input (const gchar *lun, GError **error);
 
 /**
  * bd_s390_zfcp_online:
- * @devno: a zFCP device number
- * @wwpn: a zFCP WWPN identifier
- * @lun: a zFCP LUN identifier
+ * @devno: zfcp device number
+ * @wwpn: zfcp WWPN (World Wide Port Number)
+ * @lun: zfcp LUN (Logical Unit Number)
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns: whether a zFCP device was successfully switched online
@@ -143,12 +143,12 @@ gboolean bd_s390_zfcp_online (const gchar *devno, const gchar *wwpn, const gchar
 
 /**
  * bd_s390_zfcp_scsi_offline:
- * @devno: a zFCP device number
- * @wwpn: a zFCP WWPN identifier
- * @lun: a zFCP LUN identifier
+ * @devno: zfcp device number
+ * @wwpn: zfcp WWPN (World Wide Port Number)
+ * @lun: zfcp LUN (Logical Unit Number)
  * @error: (out) (optional): place to store error (if any)
  *
- * Returns: whether a LUN was successfully removed from associated WWPN
+ * Returns: whether a LUN was successfully removed from its associated WWPN
  *
  * This function looks through /proc/scsi/scsi and manually removes LUNs from
  * associated WWPNs. zFCP devices are SCSI devices accessible over FCP protocol.

src/plugins/btrfs.c

@@ -448,7 +448,7 @@ gboolean bd_btrfs_delete_subvolume (const gchar *mountpoint, const gchar *name,
  * @error: (out) (optional): place to store error (if any)
  *
  * Returns: ID of the @mountpoint volume's default subvolume. If 0,
- * @error) may be set to indicate error
+ *          @error may be set to indicate error
  *
  * Tech category: %BD_BTRFS_TECH_SUBVOL-%BD_BTRFS_TECH_MODE_QUERY
  */