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

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

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 |