Documentation: Fix doxygen errors

Change-Id: I195fd3a9c7fc07c35913342d2041e1ffef110466
Signed-off-by: Martin Roth <martinroth@google.com>
Reviewed-on: https://review.coreboot.org/15549
Tested-by: build bot (Jenkins)
Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net>
Reviewed-by: Patrick Georgi <pgeorgi@google.com>

2 files changed, 75 insertions, 90 deletions

diff --git a/src/soc/nvidia/tegra132/include/soc/mipi_dsi.h b/src/soc/nvidia/tegra132/include/soc/mipi_dsi.h
index 73cf9b0a7c..b8a9a8684e 100644
--- a/src/soc/nvidia/tegra132/include/soc/mipi_dsi.h
+++ b/src/soc/nvidia/tegra132/include/soc/mipi_dsi.h
@@ -35,32 +35,28 @@ struct mipi_dsi_device;
 #define MIPI_DSI_MSG_USE_LPM	BIT(1)
 
 /**
- * struct mipi_dsi_msg - read/write DSI buffer
- * @channel: virtual channel id
- * @type: payload data type
- * @flags: flags controlling this message transmission
- * @tx_len: length of @tx_buf
- * @tx_buf: data to be written
- * @rx_len: length of @rx_buf
- * @rx_buf: data to be read, or NULL
+ * @brief mipi_dsi_msg - read/write DSI buffer
  */
 struct mipi_dsi_msg {
-	u8 channel;
-	u8 type;
-	u16 flags;
+	u8 channel;		/**< virtual channel id */
+	u8 type;		/**< payload data type */
+	u16 flags;		/**< flags controlling this message transmission */
 
-	size_t tx_len;
-	const void *tx_buf;
+	size_t tx_len;		/**< length of tx_buf */
+	const void *tx_buf;	/**< data to be written */
 
-	size_t rx_len;
-	void *rx_buf;
+	size_t rx_len;		/**< length of rx_buf */
+	void *rx_buf;		/**< data to be read, or NULL */
 };
 
 /**
- * struct mipi_dsi_host_ops - DSI bus operations
- * @attach: attach DSI device to DSI host
- * @detach: detach DSI device from DSI host
- * @transfer: transmit a DSI packet
+ * @brief mipi_dsi_host_ops - DSI bus operations
+ * @var mipi_dsi_host_ops::attach
+ *      attach DSI device to DSI host
+ * @var mipi_dsi_host_ops::detach
+ *      detach DSI device from DSI host
+ * @var mipi_dsi_host_ops::transfer
+ *     transmit a DSI packet
  *
  * DSI packets transmitted by .transfer() are passed in as mipi_dsi_msg
  * structures. This structure contains information about the type of packet
@@ -84,14 +80,12 @@ struct mipi_dsi_host_ops {
 };
 
 /**
- * struct mipi_dsi_host - DSI host device
- * @dev: driver model device node for this DSI host
- * @ops: DSI host operations
+ * @brief mipi_dsi_host - DSI host device
  */
 struct mipi_dsi_host {
 	//struct device *dev;
-	void *dev;
-	const struct mipi_dsi_host_ops *ops;
+	void *dev;	/**< driver model device node for this DSI host */
+	const struct mipi_dsi_host_ops *ops; /**< DSI host operations */
 };
 
 int mipi_dsi_host_register(struct mipi_dsi_host *host);
@@ -136,32 +130,23 @@ struct mipi_dsi_master_ops {
 };
 
 /**
- * struct mipi_dsi_device - DSI peripheral device
- * @host: DSI host for this peripheral
- * @dev: driver model device node for this peripheral
- * @channel: virtual channel assigned to the peripheral
- * @format: pixel format for video mode
- * @lanes: number of active data lanes
- * @mode_flags: DSI operation mode related flags
- * @ops: callbacks for master/slave setup
- * @master: master interface for dual-channel peripherals
- * @slave: slave interface for dual-channel peripherals
+ * @brief mipi_dsi_device - DSI peripheral device
  *
  * For dual-channel interfaces, the master interface can be identified by the
  * fact that it's .slave field is set to non-NULL. The slave interface will
  * have the .master field set to non-NULL.
  */
 struct mipi_dsi_device {
-	struct mipi_dsi_host *host;
+	struct mipi_dsi_host *host;	/**< DSI host for this peripheral */
 
-	unsigned int channel;
-	unsigned int lanes;
-	enum mipi_dsi_pixel_format format;
-	unsigned long mode_flags;
+	unsigned int channel;	/**< virtual channel assigned to the peripheral */
+	unsigned int lanes;	/**< number of active data lanes */
+	enum mipi_dsi_pixel_format format;	/**< pixel format for video mode */
+	unsigned long mode_flags;	/**< DSI operation mode related flags */
 
-	const struct mipi_dsi_master_ops *ops;
-	struct mipi_dsi_device *master;
-	struct mipi_dsi_device *slave;
+	const struct mipi_dsi_master_ops *ops;	/**< callbacks for master/slave setup */
+	struct mipi_dsi_device *master;	/**< master interface for dual-channel peripherals */
+	struct mipi_dsi_device *slave;	/**< slave interface for dual-channel peripherals */
 };
 
 int mipi_dsi_attach(struct mipi_dsi_device *dsi);
@@ -172,11 +157,12 @@ int mipi_dsi_liberate(struct mipi_dsi_device *master,
 		      struct mipi_dsi_device *slave);
 
 /**
- * enum mipi_dsi_dcs_tear_mode - Tearing Effect Output Line mode
- * @MIPI_DSI_DCS_TEAR_MODE_VBLANK: the TE output line consists of V-Blanking
- *    information only
- * @MIPI_DSI_DCS_TEAR_MODE_VHBLANK : the TE output line consists of both
- *    V-Blanking and H-Blanking information
+ * @brief mipi_dsi_dcs_tear_mode - Tearing Effect Output Line mode
+ * @var mipi_dsi_dcs_tear_mode::MIPI_DSI_DCS_TEAR_MODE_VBLANK
+ *     the TE output line consists of V-Blanking information only
+ * @var mipi_dsi_dcs_tear_mode::MIPI_DSI_DCS_TEAR_MODE_VHBLANK
+ *      the TE output line consists of both V-Blanking and H-Blanking
+ *      information
  */
 enum mipi_dsi_dcs_tear_mode {
 	MIPI_DSI_DCS_TEAR_MODE_VBLANK,
diff --git a/src/soc/nvidia/tegra132/mipi_dsi.c b/src/soc/nvidia/tegra132/mipi_dsi.c
index bb313f6a34..d273a75419 100644
--- a/src/soc/nvidia/tegra132/mipi_dsi.c
+++ b/src/soc/nvidia/tegra132/mipi_dsi.c
@@ -105,7 +105,7 @@ int mipi_dsi_host_register(struct mipi_dsi_host *host)
 
 /**
  * mipi_dsi_attach - attach a DSI device to its DSI host
- * @dsi: DSI peripheral
+ * @param dsi: DSI peripheral
  */
 int mipi_dsi_attach(struct mipi_dsi_device *dsi)
 {
@@ -119,7 +119,7 @@ int mipi_dsi_attach(struct mipi_dsi_device *dsi)
 
 /**
  * mipi_dsi_detach - detach a DSI device from its DSI host
- * @dsi: DSI peripheral
+ * @param dsi: DSI peripheral
  */
 int mipi_dsi_detach(struct mipi_dsi_device *dsi)
 {
@@ -134,10 +134,10 @@ int mipi_dsi_detach(struct mipi_dsi_device *dsi)
 /**
  * mipi_dsi_enslave() - use a MIPI DSI peripheral as slave for dual-channel
  *    operation
- * @master: master DSI peripheral device
- * @slave: slave DSI peripheral device
+ * @param master: master DSI peripheral device
+ * @param slave: slave DSI peripheral device
  *
- * Return: 0 on success or a negative error code on failure.
+ * @return 0 on success or a negative error code on failure.
  */
 int mipi_dsi_enslave(struct mipi_dsi_device *master,
 		     struct mipi_dsi_device *slave)
@@ -156,10 +156,10 @@ int mipi_dsi_enslave(struct mipi_dsi_device *master,
 /**
  * mipi_dsi_liberate() - stop using a MIPI DSI peripheral as slave for dual-
  *    channel operation
- * @master: master DSI peripheral device
- * @slave: slave DSI peripheral device
+ * @param master: master DSI peripheral device
+ * @param slave: slave DSI peripheral device
  *
- * Return: 0 on success or a negative error code on failure.
+ * @return 0 on success or a negative error code on failure.
  */
 int mipi_dsi_liberate(struct mipi_dsi_device *master,
 		      struct mipi_dsi_device *slave)
@@ -177,16 +177,15 @@ int mipi_dsi_liberate(struct mipi_dsi_device *master,
 
 /**
  * mipi_dsi_dcs_write() - send DCS write command
- * @dsi: DSI peripheral device
- * @cmd: DCS command
- * @data: buffer containing the command payload
- * @len: command payload length
+ * @param dsi: DSI peripheral device
+ * @param cmd: DCS command
+ * @param data: buffer containing the command payload
+ * @param len: command payload length
  *
  * This function will automatically choose the right data type depending on
  * the command payload length.
  *
- * Return: The number of bytes successfully transmitted or a negative error
- * code on failure.
+ * @return The number of bytes successfully transmitted or a negative error code on failure.
  */
 ssize_t mipi_dsi_dcs_write(struct mipi_dsi_device *dsi, u8 cmd,
 			   const void *data, size_t len)
@@ -261,9 +260,9 @@ ssize_t mipi_dsi_dcs_write(struct mipi_dsi_device *dsi, u8 cmd,
 /**
  * mipi_dsi_dcs_exit_sleep_mode() - enable all blocks inside the display
  *    module
- * @dsi: DSI peripheral device
+ * @param dsi: DSI peripheral device
  *
- * Return: 0 on success or a negative error code on failure.
+ * @return 0 on success or a negative error code on failure.
  */
 int mipi_dsi_dcs_exit_sleep_mode(struct mipi_dsi_device *dsi)
 {
@@ -279,9 +278,9 @@ int mipi_dsi_dcs_exit_sleep_mode(struct mipi_dsi_device *dsi)
 /**
  * mipi_dsi_dcs_set_display_on() - start displaying the image data on the
  *    display device
- * @dsi: DSI peripheral device
+ * @param dsi: DSI peripheral device
  *
- * Return: 0 on success or a negative error code on failure
+ * @return 0 on success or a negative error code on failure
  */
 int mipi_dsi_dcs_set_display_on(struct mipi_dsi_device *dsi)
 {
@@ -297,11 +296,11 @@ int mipi_dsi_dcs_set_display_on(struct mipi_dsi_device *dsi)
 /**
  * mipi_dsi_dcs_set_column_address() - define the column extent of the frame
  *    memory accessed by the host processor
- * @dsi: DSI peripheral device
- * @start: first column of frame memory
- * @end: last column of frame memory
+ * @param dsi: DSI peripheral device
+ * @param start: first column of frame memory
+ * @param end: last column of frame memory
  *
- * Return: 0 on success or a negative error code on failure.
+ * @return 0 on success or a negative error code on failure.
  */
 int mipi_dsi_dcs_set_column_address(struct mipi_dsi_device *dsi, u16 start,
 				    u16 end)
@@ -320,11 +319,11 @@ int mipi_dsi_dcs_set_column_address(struct mipi_dsi_device *dsi, u16 start,
 /**
  * mipi_dsi_dcs_set_page_address() - define the page extent of the frame
  *    memory accessed by the host processor
- * @dsi: DSI peripheral device
- * @start: first page of frame memory
- * @end: last page of frame memory
+ * @param dsi: DSI peripheral device
+ * @param start: first page of frame memory
+ * @param end: last page of frame memory
  *
- * Return: 0 on success or a negative error code on failure.
+ * @return: 0 on success or a negative error code on failure.
  */
 int mipi_dsi_dcs_set_page_address(struct mipi_dsi_device *dsi, u16 start,
 				  u16 end)
@@ -343,10 +342,10 @@ int mipi_dsi_dcs_set_page_address(struct mipi_dsi_device *dsi, u16 start,
 /**
  * mipi_dsi_dcs_set_tear_on() - turn on the display module's Tearing Effect
  *    output signal on the TE signal line.
- * @dsi: DSI peripheral device
- * @mode: the Tearing Effect Output Line mode
+ * @param dsi: DSI peripheral device
+ * @param mode: the Tearing Effect Output Line mode
  *
- * Return: 0 on success or a negative error code on failure
+ * @return 0 on success or a negative error code on failure
  */
 int mipi_dsi_dcs_set_tear_on(struct mipi_dsi_device *dsi,
 			     enum mipi_dsi_dcs_tear_mode mode)
@@ -363,12 +362,12 @@ int mipi_dsi_dcs_set_tear_on(struct mipi_dsi_device *dsi,
 }
 
 /**
- * mipi_dsi_dcs_set_pixel_format() - sets the pixel format for the RGB image
+ * @brief mipi_dsi_dcs_set_pixel_format() - sets the pixel format for the RGB image
  *    data used by the interface
- * @dsi: DSI peripheral device
- * @format: pixel format
+ * @param dsi: DSI peripheral device
+ * @param format: pixel format
  *
- * Return: 0 on success or a negative error code on failure.
+ * @return 0 on success or a negative error code on failure.
  */
 int mipi_dsi_dcs_set_pixel_format(struct mipi_dsi_device *dsi, u8 format)
 {
@@ -385,17 +384,17 @@ int mipi_dsi_dcs_set_pixel_format(struct mipi_dsi_device *dsi, u8 format)
 /**
  * mipi_dsi_dcs_set_address_mode() - sets the data order for forward transfers
  *    from the host to the peripheral
- * @dsi: DSI peripheral device
- * @reverse_page_address: reverses the page addressing to bottom->top
- * @reverse_col_address: reverses the column addressing to right->left
- * @reverse_page_col_address: reverses the page/column addressing order
- * @refresh_from_bottom: refresh the display bottom to top
- * @reverse_rgb: send pixel data bgr instead of rgb
- * @latch_right_to_left: latch the incoming display data right to left
- * @flip_horizontal: flip the image horizontally, left to right
- * @flip_vertical: flip the image vertically, top to bottom
+ * @param dsi: DSI peripheral device
+ * @param reverse_page_address: reverses the page addressing to bottom->top
+ * @param reverse_col_address: reverses the column addressing to right->left
+ * @param reverse_page_col_address: reverses the page/column addressing order
+ * @param refresh_from_bottom: refresh the display bottom to top
+ * @param reverse_rgb: send pixel data bgr instead of rgb
+ * @param latch_right_to_left: latch the incoming display data right to left
+ * @param flip_horizontal: flip the image horizontally, left to right
+ * @param flip_vertical: flip the image vertically, top to bottom
  *
- * Return: 0 on success or a negative error code on failure.
+ * @return 0 on success or a negative error code on failure.
  */
 int mipi_dsi_dcs_set_address_mode(struct mipi_dsi_device *dsi,
 			bool reverse_page_address,