From 2ca34c67ce5bcfe7d715d7b80c7e7426ab3627cb Mon Sep 17 00:00:00 2001 From: Vojtech Trefny Date: Wed, 18 Mar 2026 15:21:29 +0100 Subject: [PATCH] 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 --- src/lib/plugin_apis/crypto.api | 6 +++--- src/lib/plugin_apis/dm.api | 3 ++- src/lib/plugin_apis/fs.api | 2 ++ src/lib/plugin_apis/loop.api | 3 ++- src/lib/plugin_apis/mdraid.api | 4 ++-- src/lib/plugin_apis/nvdimm.api | 11 ++++++----- src/lib/plugin_apis/nvme.api | 2 +- src/lib/plugin_apis/part.api | 2 +- src/lib/plugin_apis/s390.api | 18 +++++++++--------- src/plugins/btrfs.c | 2 +- src/plugins/crypto.c | 2 +- src/plugins/dm.c | 6 +++--- src/plugins/fs/mount.c | 3 ++- src/plugins/lvm/lvm-dbus.c | 4 ++-- src/plugins/lvm/lvm.c | 2 +- src/plugins/nvdimm.c | 2 +- src/plugins/nvme/nvme-op.c | 2 +- src/plugins/part.c | 2 +- src/plugins/s390.c | 2 +- 19 files changed, 42 insertions(+), 36 deletions(-) diff --git a/src/lib/plugin_apis/crypto.api b/src/lib/plugin_apis/crypto.api index 3ebdfde55..d790894c9 100644 --- a/src/lib/plugin_apis/crypto.api +++ b/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 diff --git a/src/lib/plugin_apis/dm.api b/src/lib/plugin_apis/dm.api index 469fe5a19..ed128bfa7 100644 --- a/src/lib/plugin_apis/dm.api +++ b/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 */ diff --git a/src/lib/plugin_apis/fs.api b/src/lib/plugin_apis/fs.api index b42653bc8..0f3ffe5e9 100644 --- a/src/lib/plugin_apis/fs.api +++ b/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 diff --git a/src/lib/plugin_apis/loop.api b/src/lib/plugin_apis/loop.api index 770d355a2..c55e0c56d 100644 --- a/src/lib/plugin_apis/loop.api +++ b/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 */ diff --git a/src/lib/plugin_apis/mdraid.api b/src/lib/plugin_apis/mdraid.api index 00cff9b71..101412813 100644 --- a/src/lib/plugin_apis/mdraid.api +++ b/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 diff --git a/src/lib/plugin_apis/nvdimm.api b/src/lib/plugin_apis/nvdimm.api index 7f6310a9e..ec92e0af9 100644 --- a/src/lib/plugin_apis/nvdimm.api +++ b/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 @@ -234,7 +233,7 @@ BDNVDIMMNamespaceInfo** bd_nvdimm_list_namespaces (const gchar *bus, const gchar /** * bd_nvdimm_namespace_reconfigure: * @namespace: name of the namespace to reconfigure - * @mode: mode type to set (memory/sector/raw/dax) + * @mode: mode type to set (raw/sector/memory/dax/fsdax/devdax) * @force: whether to use force to reconfigure an active namespace * @error: (out) (optional): place to store error if any * @extra: (nullable) (array zero-terminated=1): extra options for the creation (right now @@ -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); diff --git a/src/lib/plugin_apis/nvme.api b/src/lib/plugin_apis/nvme.api index 08cd2f990..85bbe2bbd 100644 --- a/src/lib/plugin_apis/nvme.api +++ b/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 was successfully submitted, %FALSE otherwise with @error set. * * Tech category: %BD_NVME_TECH_NVME-%BD_NVME_TECH_MODE_MANAGE */ diff --git a/src/lib/plugin_apis/part.api b/src/lib/plugin_apis/part.api index 89d8c6c1f..a5358e29e 100644 --- a/src/lib/plugin_apis/part.api +++ b/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); diff --git a/src/lib/plugin_apis/s390.api b/src/lib/plugin_apis/s390.api index c5e57c855..ec8242ae6 100644 --- a/src/lib/plugin_apis/s390.api +++ b/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. diff --git a/src/plugins/btrfs.c b/src/plugins/btrfs.c index 5040abdf2..069b5032d 100644 --- a/src/plugins/btrfs.c +++ b/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 */ diff --git a/src/plugins/crypto.c b/src/plugins/crypto.c index 36486b339..6acff94e3 100644 --- a/src/plugins/crypto.c +++ b/src/plugins/crypto.c @@ -3185,7 +3185,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/#detection + * 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 diff --git a/src/plugins/dm.c b/src/plugins/dm.c index 58b390333..a13249816 100644 --- a/src/plugins/dm.c +++ b/src/plugins/dm.c @@ -169,7 +169,7 @@ gboolean bd_dm_remove (const gchar *map_name, GError **error) { * @error: (out) (optional): place to store error (if any) * * Returns: map name of the map providing the @dm_node device or %NULL - * (@error) contains the error in such cases) + * (@error) contains the error in such cases * * Tech category: %BD_DM_TECH_MAP-%BD_DM_TECH_MODE_QUERY */ @@ -208,7 +208,7 @@ gchar* bd_dm_name_from_node (const gchar *dm_node, GError **error) { * @error: (out) (optional): place to store error (if any) * * Returns: DM node name for the @map_name map or %NULL (@error) contains - * the error in such cases) + * the error in such cases * * Tech category: %BD_DM_TECH_MAP-%BD_DM_TECH_MODE_QUERY */ @@ -306,7 +306,7 @@ gchar* bd_dm_get_subsystem_from_name (const gchar *device_name, GError **error) * * Returns: whether the given @map_name exists (and is live if @live_only is * %TRUE (and is active if @active_only is %TRUE)). If %FALSE is returned, - * @error) indicates whether error appeared (non-%NULL) or not (%NULL). + * @error indicates whether error appeared (non-%NULL) or not (%NULL). * * Tech category: %BD_DM_TECH_MAP-%BD_DM_TECH_MODE_QUERY */ diff --git a/src/plugins/fs/mount.c b/src/plugins/fs/mount.c index 05f272d58..c310911f9 100644 --- a/src/plugins/fs/mount.c +++ b/src/plugins/fs/mount.c @@ -634,11 +634,12 @@ static gboolean run_as_user (MountFunc func, MountArgs *args, uid_t run_as_uid, * 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 * - * Tech category: %BD_FS_TECH_GENERIC (no mode, ignored) + * Tech category: %BD_FS_TECH_MOUNT (no mode, ignored) */ gboolean bd_fs_unmount (const gchar *spec, gboolean lazy, gboolean force, const BDExtraArg **extra, GError **error) { uid_t run_as_uid = -1; diff --git a/src/plugins/lvm/lvm-dbus.c b/src/plugins/lvm/lvm-dbus.c index 9a79f728c..345e27f29 100644 --- a/src/plugins/lvm/lvm-dbus.c +++ b/src/plugins/lvm/lvm-dbus.c @@ -3836,7 +3836,7 @@ gboolean bd_lvm_vdo_enable_deduplication (const gchar *vg_name, const gchar *poo } /** - * bd_lvm_vdo_enable_deduplication: + * bd_lvm_vdo_disable_deduplication: * @vg_name: name of the VG containing the to-be-changed VDO pool LV * @pool_name: name of the VDO pool LV to disable deduplication on * @extra: (nullable) (array zero-terminated=1): extra options for the VDO change @@ -3854,7 +3854,7 @@ gboolean bd_lvm_vdo_disable_deduplication (const gchar *vg_name, const gchar *po /** * bd_lvm_vdo_info: * @vg_name: name of the VG that contains the LV to get information about - * @pool_name: name of the VDO pool LV to get information about + * @lv_name: name of the LV to get information about * @error: (out) (optional): place to store error (if any) * * Returns: (transfer full): information about the @vg_name/@lv_name LV or %NULL in case diff --git a/src/plugins/lvm/lvm.c b/src/plugins/lvm/lvm.c index a049f9ef3..b432f41bd 100644 --- a/src/plugins/lvm/lvm.c +++ b/src/plugins/lvm/lvm.c @@ -2755,7 +2755,7 @@ gboolean bd_lvm_vdo_enable_deduplication (const gchar *vg_name, const gchar *poo } /** - * bd_lvm_vdo_enable_deduplication: + * bd_lvm_vdo_disable_deduplication: * @vg_name: name of the VG containing the to-be-changed VDO pool LV * @pool_name: name of the VDO pool LV to disable deduplication on * @extra: (nullable) (array zero-terminated=1): extra options for the VDO change diff --git a/src/plugins/nvdimm.c b/src/plugins/nvdimm.c index c26b1f948..bb9e5817e 100644 --- a/src/plugins/nvdimm.c +++ b/src/plugins/nvdimm.c @@ -593,7 +593,7 @@ BDNVDIMMNamespaceInfo** bd_nvdimm_list_namespaces (const gchar *bus_name, const /** * bd_nvdimm_namespace_reconfigure: * @namespace: name of the namespace to reconfigure - * @mode: mode type to set + * @mode: mode type to set (raw/sector/memory/dax/fsdax/devdax) * @force: whether to use force to reconfigure an active namespace * @error: (out) (optional): place to store error if any * @extra: (nullable) (array zero-terminated=1): extra options for the creation (right now diff --git a/src/plugins/nvme/nvme-op.c b/src/plugins/nvme/nvme-op.c index 90e64ca32..962722222 100644 --- a/src/plugins/nvme/nvme-op.c +++ b/src/plugins/nvme/nvme-op.c @@ -349,7 +349,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 was successfully submitted, %FALSE otherwise with @error set. * * Tech category: %BD_NVME_TECH_NVME-%BD_NVME_TECH_MODE_MANAGE */ diff --git a/src/plugins/part.c b/src/plugins/part.c index 2878b99fa..7a3533b30 100644 --- a/src/plugins/part.c +++ b/src/plugins/part.c @@ -1799,7 +1799,7 @@ static gboolean set_part_type (struct fdisk_context *cxt, gint part_num, const g * * Returns: whether the name was successfully set 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_name (const gchar *disk, const gchar *part, const gchar *name, GError **error) { struct fdisk_context *cxt = NULL; diff --git a/src/plugins/s390.c b/src/plugins/s390.c index 841dcc707..60733176c 100644 --- a/src/plugins/s390.c +++ b/src/plugins/s390.c @@ -729,7 +729,7 @@ gboolean bd_s390_zfcp_online (const gchar *devno, const gchar *wwpn, const gchar * I/O config, but WWPN and LUN configuration is done at the OS level, hence * this function becomes necessary when switching the device offline. This * particular sequence of actions is for some reason unnecessary when switching - * the device offline. Chalk it up to s390x being s390x. + * the device online. Chalk it up to s390x being s390x. * * Tech category: %BD_S390_TECH_ZFCP-%BD_S390_TECH_MODE_MODIFY */