[PATCH] driver: convert struct device comments to kernel-doc style

[PATCH] driver: convert struct device comments to kernel-doc style

[Bo Sun]

Convert the comments of struct device from the old style to standard
kernel-doc style.

No functional changes.

Signed-off-by: Bo Sun <bo@mboxify.com>
---
As suggested, I took the opportunity to switch struct device comments
to kernel-doc style.

 include/device.h | 86 +++++++++++++++++++++++++++---------------------
 1 file changed, 48 insertions(+), 38 deletions(-)

diff --git a/include/device.h b/include/device.h
index 97fa040365..965251e552 100644
--- a/include/device.h
+++ b/include/device.h
@@ -24,24 +24,48 @@ struct generic_pm_domain;
 struct platform_device_id;
 struct of_device_id;
 
-/** @brief Describes a particular device present in the system */
+/**
+ * struct device - The basic device structure
+ * @name: This member is used to match with a driver. This is a
+ *        descriptive name and could be MPC5XXX_ether or imx_serial.
+ *        Unless absolutely necessary, should not be modified
+ *        directly and dev_set_name() should be used instead.
+ * @unique_name: Device's unique name as obtained by calling dev_id().
+ *               Internal field, do not access it directly.
+ * @id: Used to uniquely identify a device in the system. The id
+ *      will show up under /dev/ as the device's name. Usually this
+ *      is something like eth0 or nor0.
+ * @dma_coherent: DMA coherence setting for this device.
+ * @resource: Array of resources for this device.
+ * @num_resources: Number of resources in the resource array.
+ * @platform_data: Board specific information about this device.
+ * @priv: Device class specific data storage.
+ * @driver_data: Alternative name for @priv
+ * @type_data: In case this device is a specific device, this pointer
+ *             points to the type specific device, i.e. eth_device
+ * @driver: The driver for this device.
+ * @list: The list of all devices.
+ * @bus_list: Our bus.
+ * @children: Our children.
+ * @sibling: Our siblings.
+ * @active: The list of all devices which have a driver
+ * @parent: The device's "parent" device, the device to which it is attached.
+ *          If parent is NULL, the device is a top-level device.
+ * @pm_domain: Attached power domain.
+ * @bus: Type of bus device is on.
+ * @parameters: The parameters for this device. This is used to carry information
+ *              of board specific data from the board code to the device driver
+ * @dma_mask: DMA mask.
+ * @dma_offset: DMA offset.
+ * @detect: For devices which take longer to probe, this is called when the driver
+ *          should actually detect client devices.
+ * @rescan: Callback to rescan the device.
+ * @deferred_probe_reason: If a driver probe is deferred, this stores the last error.
+ */
 struct device {
-	/*! This member (and 'type' described below) is used to match
-	 * with a driver. This is a descriptive name and could be
-	 * MPC5XXX_ether or imx_serial. Unless absolutely necessary,
-	 * should not be modified directly and dev_set_name() should
-	 * be used instead.
-	 */
 	char *name;
 
-	/*! This member is used to store device's unique name as
-	 *  obtained by calling dev_id(). Internal field, do not
-	 *  access it directly.
-	 */
 	char *unique_name;
-	/*! The id is used to uniquely identify a device in the system. The id
-	 * will show up under /dev/ as the device's name. Usually this is
-	 * something like eth0 or nor0. */
 	int id;
 
 	enum dev_dma_coherence dma_coherent;
@@ -49,36 +73,29 @@ struct device {
 	struct resource *resource;
 	int num_resources;
 
-	void *platform_data; /*! board specific information about this device */
+	void *platform_data;
 
-	/*! Devices of a particular class normaly need to store more
-	 * information than struct device holds.
-	 */
 	union {
 		void *priv;
 		void *driver_data;
 	};
-	/*! In case this device is a specific device, this pointer
-	 * points to the type specific device, i.e. eth_device
-	 */
+
 	void *type_data;
 
-	struct driver *driver; /*! The driver for this device */
+	struct driver *driver;
 
-	struct list_head list;     /* The list of all devices */
-	struct list_head bus_list; /* our bus */
-	struct list_head children; /* our children */
+	struct list_head list;
+	struct list_head bus_list;
+	struct list_head children;
 	struct list_head sibling;
-	struct list_head active;   /* The list of all devices which have a driver */
+	struct list_head active;
 
-	struct device *parent;   /* our parent, NULL if not present */
+	struct device *parent;
 
-	struct generic_pm_domain *pm_domain;	/* attached power domain */
+	struct generic_pm_domain *pm_domain;
 
 	struct bus_type *bus;
 
-	/*! The parameters for this device. This is used to carry information
-	 * of board specific data from the board code to the device driver. */
 	struct list_head parameters;
 
 	struct list_head cdevs;
@@ -90,7 +107,6 @@ struct device {
 		struct device_node *device_node;
 		struct device_node *of_node;
 	};
-
 	const struct of_device_id *of_id_entry;
 
 	u64 dma_mask;
@@ -100,16 +116,10 @@ struct device {
 #ifdef CONFIG_CMD_DEVINFO
 	struct list_head info_list;
 #endif
-	/*
-	 * For devices which take longer to probe this is called
-	 * when the driver should actually detect client devices
-	 */
+
 	int (*detect)(struct device *);
 	void (*rescan)(struct device *);
 
-	/*
-	 * if a driver probe is deferred, this stores the last error
-	 */
 	char *deferred_probe_reason;
 };
 

Re: [PATCH] driver: convert struct device comments to kernel-doc style

[Ahmad Fatoum]

Hello Bo,

On 7/17/25 15:13, Bo Sun wrote:
> Convert the comments of struct device from the old style to standard
> kernel-doc style.
> 
> No functional changes.
> 
> Signed-off-by: Bo Sun <bo@mboxify.com>

Reviewed-by: Ahmad Fatoum <a.fatoum@pengutronix.de>

> + * struct device - The basic device structure
> + * @name: This member is used to match with a driver.

While technically correct, we don't encourage match by name, but instead
match by match table, most often device tree compatible.

I will send a patch to update the docs once this is applied.

Thanks,
Ahmad

> This is a
> + *        descriptive name and could be MPC5XXX_ether or imx_serial.
> + *        Unless absolutely necessary, should not be modified
> + *        directly and dev_set_name() should be used instead.



> + * @unique_name: Device's unique name as obtained by calling dev_id().
> + *               Internal field, do not access it directly.
> + * @id: Used to uniquely identify a device in the system. The id
> + *      will show up under /dev/ as the device's name. Usually this
> + *      is something like eth0 or nor0.
> + * @dma_coherent: DMA coherence setting for this device.
> + * @resource: Array of resources for this device.
> + * @num_resources: Number of resources in the resource array.
> + * @platform_data: Board specific information about this device.
> + * @priv: Device class specific data storage.
> + * @driver_data: Alternative name for @priv
> + * @type_data: In case this device is a specific device, this pointer
> + *             points to the type specific device, i.e. eth_device
> + * @driver: The driver for this device.
> + * @list: The list of all devices.
> + * @bus_list: Our bus.
> + * @children: Our children.
> + * @sibling: Our siblings.
> + * @active: The list of all devices which have a driver
> + * @parent: The device's "parent" device, the device to which it is attached.
> + *          If parent is NULL, the device is a top-level device.
> + * @pm_domain: Attached power domain.
> + * @bus: Type of bus device is on.
> + * @parameters: The parameters for this device. This is used to carry information
> + *              of board specific data from the board code to the device driver
> + * @dma_mask: DMA mask.
> + * @dma_offset: DMA offset.
> + * @detect: For devices which take longer to probe, this is called when the driver
> + *          should actually detect client devices.
> + * @rescan: Callback to rescan the device.
> + * @deferred_probe_reason: If a driver probe is deferred, this stores the last error.
> + */
>  struct device {
> -	/*! This member (and 'type' described below) is used to match
> -	 * with a driver. This is a descriptive name and could be
> -	 * MPC5XXX_ether or imx_serial. Unless absolutely necessary,
> -	 * should not be modified directly and dev_set_name() should
> -	 * be used instead.
> -	 */
>  	char *name;
>  
> -	/*! This member is used to store device's unique name as
> -	 *  obtained by calling dev_id(). Internal field, do not
> -	 *  access it directly.
> -	 */
>  	char *unique_name;
> -	/*! The id is used to uniquely identify a device in the system. The id
> -	 * will show up under /dev/ as the device's name. Usually this is
> -	 * something like eth0 or nor0. */
>  	int id;
>  
>  	enum dev_dma_coherence dma_coherent;
> @@ -49,36 +73,29 @@ struct device {
>  	struct resource *resource;
>  	int num_resources;
>  
> -	void *platform_data; /*! board specific information about this device */
> +	void *platform_data;
>  
> -	/*! Devices of a particular class normaly need to store more
> -	 * information than struct device holds.
> -	 */
>  	union {
>  		void *priv;
>  		void *driver_data;
>  	};
> -	/*! In case this device is a specific device, this pointer
> -	 * points to the type specific device, i.e. eth_device
> -	 */
> +
>  	void *type_data;
>  
> -	struct driver *driver; /*! The driver for this device */
> +	struct driver *driver;
>  
> -	struct list_head list;     /* The list of all devices */
> -	struct list_head bus_list; /* our bus */
> -	struct list_head children; /* our children */
> +	struct list_head list;
> +	struct list_head bus_list;
> +	struct list_head children;
>  	struct list_head sibling;
> -	struct list_head active;   /* The list of all devices which have a driver */
> +	struct list_head active;
>  
> -	struct device *parent;   /* our parent, NULL if not present */
> +	struct device *parent;
>  
> -	struct generic_pm_domain *pm_domain;	/* attached power domain */
> +	struct generic_pm_domain *pm_domain;
>  
>  	struct bus_type *bus;
>  
> -	/*! The parameters for this device. This is used to carry information
> -	 * of board specific data from the board code to the device driver. */
>  	struct list_head parameters;
>  
>  	struct list_head cdevs;
> @@ -90,7 +107,6 @@ struct device {
>  		struct device_node *device_node;
>  		struct device_node *of_node;
>  	};
> -
>  	const struct of_device_id *of_id_entry;
>  
>  	u64 dma_mask;
> @@ -100,16 +116,10 @@ struct device {
>  #ifdef CONFIG_CMD_DEVINFO
>  	struct list_head info_list;
>  #endif
> -	/*
> -	 * For devices which take longer to probe this is called
> -	 * when the driver should actually detect client devices
> -	 */
> +
>  	int (*detect)(struct device *);
>  	void (*rescan)(struct device *);
>  
> -	/*
> -	 * if a driver probe is deferred, this stores the last error
> -	 */
>  	char *deferred_probe_reason;
>  };
>  
> 

-- 
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

Re: [PATCH] driver: convert struct device comments to kernel-doc style

[Sascha Hauer]

On Thu, 17 Jul 2025 21:13:39 +0800, Bo Sun wrote:
> Convert the comments of struct device from the old style to standard
> kernel-doc style.
> 
> No functional changes.
> 
> 

Applied, thanks!

[1/1] driver: convert struct device comments to kernel-doc style
      https://git.pengutronix.de/cgit/barebox/commit/?id=78d8afa4372e (link may not be stable)

Best regards,
-- 
Sascha Hauer <s.hauer@pengutronix.de>