From e86b6f71002e5892c28acd206e68d13adc76c4b7 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 28 Feb 2022 12:08:34 -0700 Subject: [PATCH] dm: core: Tidy up comments in uclass headers Improve some of the comments in these files, which don't follow the correct style. Signed-off-by: Simon Glass --- include/dm/uclass-internal.h | 18 +++++++++--------- include/dm/uclass.h | 13 ++++++------- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/include/dm/uclass-internal.h b/include/dm/uclass-internal.h index e71b86a973..daf856c03c 100644 --- a/include/dm/uclass-internal.h +++ b/include/dm/uclass-internal.h @@ -55,7 +55,7 @@ * * @_name: Name of the uclass. This must be a valid C identifier, used by the * linker_list - * @returns struct uclass * for the device + * Return: struct uclass * for the device */ #define DM_UCLASS_REF(_name) \ ll_entry_ref(struct uclass, _name, uclass) @@ -120,7 +120,7 @@ int dev_get_uclass_index(struct udevice *dev, struct uclass **ucp); * uclass_find_device() - Return n-th child of uclass * @id: Id number of the uclass * @index: Position of the child in uclass's list - * #devp: Returns pointer to device, or NULL on error + * @devp: Returns pointer to device, or NULL on error * * The device is not prepared for use - this is an internal function. * The function uclass_get_device_tail() can be used to probe the device. @@ -133,7 +133,7 @@ int uclass_find_device(enum uclass_id id, int index, struct udevice **devp); /** * uclass_find_first_device() - Return the first device in a uclass * @id: Id number of the uclass - * #devp: Returns pointer to device, or NULL on error + * @devp: Returns pointer to device, or NULL on error * * The device is not prepared for use - this is an internal function. * The function uclass_get_device_tail() can be used to probe the device. @@ -239,7 +239,7 @@ int uclass_find_device_by_phandle(enum uclass_id id, struct udevice *parent, * Connect the device into uclass's list of devices. * * @dev: Pointer to the device - * #return 0 on success, -ve on error + * Return: 0 on success, -ve on error */ int uclass_bind_device(struct udevice *dev); @@ -250,7 +250,7 @@ int uclass_bind_device(struct udevice *dev); * Call any handled needed before uclass_unbind_device() is called * * @dev: Pointer to the device - * #return 0 on success, -ve on error + * Return: 0 on success, -ve on error */ int uclass_pre_unbind_device(struct udevice *dev); @@ -260,7 +260,7 @@ int uclass_pre_unbind_device(struct udevice *dev); * Disconnect the device from uclass's list of devices. * * @dev: Pointer to the device - * #return 0 on success, -ve on error + * Return: 0 on success, -ve on error */ int uclass_unbind_device(struct udevice *dev); @@ -277,7 +277,7 @@ static inline int uclass_unbind_device(struct udevice *dev) { return 0; } * uclass' child_pre_probe() method. * * @dev: Pointer to the device - * #return 0 on success, -ve on error + * Return: 0 on success, -ve on error */ int uclass_pre_probe_device(struct udevice *dev); @@ -288,7 +288,7 @@ int uclass_pre_probe_device(struct udevice *dev); * uclass. * * @dev: Pointer to the device - * #return 0 on success, -ve on error + * Return: 0 on success, -ve on error */ int uclass_post_probe_device(struct udevice *dev); @@ -298,7 +298,7 @@ int uclass_post_probe_device(struct udevice *dev); * Perform any pre-processing of a device that is about to be removed. * * @dev: Pointer to the device - * #return 0 on success, -ve on error + * Return: 0 on success, -ve on error */ #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE) int uclass_pre_remove_device(struct udevice *dev); diff --git a/include/dm/uclass.h b/include/dm/uclass.h index 7f33c34214..aafe652288 100644 --- a/include/dm/uclass.h +++ b/include/dm/uclass.h @@ -435,7 +435,7 @@ int uclass_probe_all(enum uclass_id id); int uclass_id_count(enum uclass_id id); /** - * uclass_id_foreach_dev() - Helper function to iteration through devices + * uclass_id_foreach_dev() - iterate through devices of a given uclass ID * * This creates a for() loop which works through the available devices in * a uclass ID in order from start to end. @@ -452,20 +452,20 @@ int uclass_id_count(enum uclass_id id); list_for_each_entry(pos, &uc->dev_head, uclass_node) /** - * uclass_foreach_dev() - Helper function to iteration through devices + * uclass_foreach_dev() - iterate through devices of a given uclass * * This creates a for() loop which works through the available devices in * a uclass in order from start to end. * * @pos: struct udevice * to hold the current device. Set to NULL when there * are no more devices. - * @uc: uclass to scan + * @uc: uclass to scan (`struct uclass *`) */ #define uclass_foreach_dev(pos, uc) \ list_for_each_entry(pos, &uc->dev_head, uclass_node) /** - * uclass_foreach_dev_safe() - Helper function to safely iteration through devs + * uclass_foreach_dev_safe() - safely iterate through devices of a given uclass * * This creates a for() loop which works through the available devices in * a uclass in order from start to end. Inside the loop, it is safe to remove @@ -474,14 +474,13 @@ int uclass_id_count(enum uclass_id id); * @pos: struct udevice * to hold the current device. Set to NULL when there * are no more devices. * @next: struct udevice * to hold the next next - * @uc: uclass to scan + * @uc: uclass to scan (`struct uclass *`) */ #define uclass_foreach_dev_safe(pos, next, uc) \ list_for_each_entry_safe(pos, next, &uc->dev_head, uclass_node) /** - * uclass_foreach_dev_probe() - Helper function to iteration through devices - * of given uclass + * uclass_foreach_dev_probe() - iterate through devices of a given uclass ID * * This creates a for() loop which works through the available devices in * a uclass in order from start to end. Devices are probed if necessary, -- 2.39.5