[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;
 };