touchpad_gt7288: replace Kernel-doc with Doxygen

When I wrote the driver I was under the mistaken impression that
Kernel-doc style documentation comments were in use it CrOS EC. Looking
at it now, Doxygen is far more common.

BUG=chromium:991365
TEST=make buildall -j
BRANCH=none

Change-Id: I25be469d362bba256fdfb7f81438da28f24bfeb5
Signed-off-by: Harry Cutts <hcutts@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1899337
Reviewed-by: Craig Hesling <hesling@chromium.org>
Commit-Queue: Craig Hesling <hesling@chromium.org>

2 files changed, 35 insertions, 30 deletions

diff --git a/driver/touchpad_gt7288.c b/driver/touchpad_gt7288.c
index 8085315886..ccc98622d5 100644
--- a/driver/touchpad_gt7288.c
+++ b/driver/touchpad_gt7288.c
@@ -33,12 +33,13 @@
 #define GT7288_REPORT_LENGTH 16
 
 /**
- * gt7288_read_desc() - Read a descriptor using the Conventional Read Mode.
- * @register_id: the register containing the descriptor to read.
- * @data: the data that is read.
- * @max_length: the maximum length of data.
+ * Reads a descriptor using the Conventional Read Mode.
  *
- * Return: EC_SUCCESS or an error code.
+ * @param[in]  register_id The register containing the descriptor to read.
+ * @param[out] data The data that is read.
+ * @param[in]  max_length The maximum length of data.
+ *
+ * @return EC_SUCCESS or an error code.
  */
 static int gt7288_read_desc(uint16_t register_id, uint8_t *data,
 			    size_t max_length)
diff --git a/driver/touchpad_gt7288.h b/driver/touchpad_gt7288.h
index f3a8642fc3..c89c586784 100644
--- a/driver/touchpad_gt7288.h
+++ b/driver/touchpad_gt7288.h
@@ -15,65 +15,69 @@
 #define GT7288_MAX_CONTACTS 5
 
 /**
- * struct gt7288_version_info - version information for the chip.
- * @product_id: HID product ID (0x01F0 for touchpads, 0x01F1 for touchscreens).
- * @version_id: the firmware version. For touchpads equipped with a fingerprint
- *              sensor, the MSB will be 1.
+ * Version information for the chip.
  */
 struct gt7288_version_info {
+	/** HID product ID (0x01F0 for touchpads, 0x01F1 for touchscreens). */
 	uint16_t product_id;
+	/**
+	 * The firmware version. For touchpads equipped with a fingerprint
+	 * sensor, the MSB will be 1.
+	 */
 	uint16_t version_id;
 };
 
 /**
- * gt7288_get_version_info() - Reads version information from the GT7288.
- * @info: the version information.
+ * Reads version information from the GT7288.
  *
- * Return: EC_SUCCESS or an error code.
+ * @param[out] info The version information.
+ *
+ * @return EC_SUCCESS or an error code.
  */
 int gt7288_get_version_info(struct gt7288_version_info *info);
 
 /**
- * struct gt7288_contact - data describing a single contact.
- * @id: a 4-bit ID that uniquely identifies the contact during its lifecycle.
- * @x: the absolute X coordinate.
- * @y: the absolute Y coordinate.
- * @width: the width of the contact (with firmware version 0x0004 or greater).
- * @height: the height of the contact (with firmware version 0x0004 or greater).
- * @tip: whether the fingertip is touching the pad. (Currently always true.)
- * @confidence: whether the controller considers the touch a finger (true) or
- *              palm (false).
+ * Data describing a single contact.
  */
 struct gt7288_contact {
+	/**
+	 * A 4-bit ID that uniquely identifies the contact during its lifecycle.
+	 */
 	uint8_t id;
+	/** The absolute X coordinate. */
 	uint16_t x;
+	/** The absolute Y coordinate. */
 	uint16_t y;
+	/** The width of the contact (with firmware version 4 or greater). */
 	uint8_t width;
+	/** The height of the contact (with firmware version 4 or greater). */
 	uint8_t height;
+	/** Whether the finger is touching the pad. (Currently always true.) */
 	bool tip;
+	/** Whether the touch is a finger (true) or palm (false). */
 	bool confidence;
 };
 
 /**
- * struct gt7288_report - data from a complete report in PTP mode.
- * @timestamp: a relative timestamp, in units of 100µs.
- * @num_contacts: the number of contacts on the pad.
- * @button_down: whether the button is pressed.
- * @contacts: an array of structs describing the individual contacts.
+ * Data from a complete report in PTP mode.
  */
 struct gt7288_ptp_report {
+	/** A relative timestamp, in units of 100µs. */
 	uint16_t timestamp;
+	/** The number of contacts on the pad. */
 	size_t num_contacts;
+	/** Whether the button is pressed. */
 	bool button_down;
+	/** An array of structs describing the individual contacts. */
 	struct gt7288_contact contacts[GT7288_MAX_CONTACTS];
 };
 
 /**
- * gt7288_read_ptp_report() - Reads a complete report, when the GT7288 is in PTP
- *                            mode.
- * @report: the report that is read.
+ * Reads a complete report, when the GT7288 is in PTP mode.
+ *
+ * @param[out] report The report that is read.
  *
- * Return: EC_SUCCESS or an error code.
+ * @return EC_SUCCESS or an error code.
  */
 int gt7288_read_ptp_report(struct gt7288_ptp_report *report);