From 871c7105f63ac8fb9a02d8d65c4d849641a55c27 Mon Sep 17 00:00:00 2001
From: Tomasz Bursztyka <tomasz.bursztyka@linux.intel.com>
Date: Fri, 19 Jun 2020 08:05:56 +0200
Subject: [PATCH] device: Fix structure documentation

Switching to proper documentation format for structures.

Fixes #26284

Signed-off-by: Tomasz Bursztyka <tomasz.bursztyka@linux.intel.com>
---
 include/device.h | 30 ++++++++++++++----------------
 include/init.h   |  6 ++++++
 2 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/include/device.h b/include/device.h
index 98c05e59115..482cfc774b0 100644
--- a/include/device.h
+++ b/include/device.h
@@ -173,45 +173,43 @@ typedef void (*device_pm_cb)(struct device *dev,
 
 /**
  * @brief Device PM info
- *
- * @param dev pointer to device structure
- * @param lock lock to synchronize the get/put operations
- * @param enable device pm enable flag
- * @param usage device usage count
- * @param fsm_state device idle internal power state
- * @param event event object to listen to the sync request events
- * @param signal signal to notify the Async API callers
  */
 struct device_pm {
+	/** Pointer to the device */
 	struct device *dev;
+	/** Lock to synchronize the get/put operations */
 	struct k_sem lock;
+	/** Device pm enable flag */
 	bool enable;
+	/** Device usage count */
 	atomic_t usage;
+	/** Device idle internal power state */
 	atomic_t fsm_state;
+	/** Work object for asynchronous calls */
 	struct k_work work;
+	/** Event object to listen to the sync request events */
 	struct k_poll_event event;
+	/** Signal to notify the Async API callers */
 	struct k_poll_signal signal;
 };
 
 /**
  * @brief Runtime device structure (in memory) per driver instance
- *
- * @param name name of the device
- * @param init init function for the driver
- * @param config_info address of driver instance config information
- * @param device_config Build time config information
- * @param driver_api pointer to structure containing the API functions for
- * the device type.
- * @param driver_data driver instance data. For driver use only
  */
 struct device {
+	/** Name of the device instance */
 	const char *name;
+	/** Address of device instance config information */
 	const void *config_info;
+	/** Address of the API structure exposed by the device instance */
 	const void *driver_api;
+	/** Address of the device instance private data */
 	void * const driver_data;
 #ifdef CONFIG_DEVICE_POWER_MANAGEMENT
+	/** Power Management function */
 	int (*device_pm_control)(struct device *device, uint32_t command,
 				 void *context, device_pm_cb cb, void *arg);
+	/** Pointer to device instance power management data */
 	struct device_pm * const pm;
 #endif
 };
diff --git a/include/init.h b/include/init.h
index cc4e863bbb7..5c76bdf6821 100644
--- a/include/init.h
+++ b/include/init.h
@@ -41,7 +41,13 @@ struct device;
  * if the init entry is not used for a device driver but a service.
  */
 struct init_entry {
+	/** Initialization function for the init entry which will take
+	 * the dev attribute as parameter. See below.
+	 */
 	int (*init)(struct device *dev);
+	/** Pointer to a device driver instance structure. Can be NULL
+	 * if the init entry is not used for a device driver but a services.
+	 */
 	struct device *dev;
 };