[PATCH wayland v3] util: Improve documentation of wl_argument

[Yong Bakos]

From: Yong Bakos <ybakos at humanoriented.com>

Standardize the doxygen comment format, add clarity to the writing, decouple
the description from specifics of usage, add see-also's, and massage the union
member type comments.

Signed-off-by: Yong Bakos <ybakos at humanoriented.com>
---
v3: Correct spelling of marhsalling.
v2: Match union member type names to actual protocol-defined type names,
    rather than their descriptions.
 src/wayland-util.h | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/src/wayland-util.h b/src/wayland-util.h
index 4dba1ed..23a897e 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -552,22 +552,25 @@ wl_fixed_from_int(int i)
 }

 /**
- * \brief A union representing all of the basic data types that can be passed
- * along the wayland wire format.
+ * Protocol message argument data types
  *
- * This union represents all of the basic data types that can be passed in the
- * wayland wire format.  It is used by dispatchers and runtime-friendly
- * versions of the event and request marshaling functions.
+ * This union represents all of the argument types in the Wayland protocol wire
+ * format. The protocol implementation uses wl_argument within its marshalling
+ * machinery for dispatching messages between a client and a compositor.
+ *
+ * \sa wl_message
+ * \sa wl_interface
+ * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-wire-Format">Wire Format</a>
  */
 union wl_argument {
-	int32_t i; /**< signed integer */
-	uint32_t u; /**< unsigned integer */
-	wl_fixed_t f; /**< fixed point */
-	const char *s; /**< string */
-	struct wl_object *o; /**< object */
-	uint32_t n; /**< new_id */
-	struct wl_array *a; /**< array */
-	int32_t h; /**< file descriptor */
+	int32_t i;           /**< `int`    */
+	uint32_t u;          /**< `uint`   */
+	wl_fixed_t f;        /**< `fixed`  */
+	const char *s;       /**< `string` */
+	struct wl_object *o; /**< `object` */
+	uint32_t n;          /**< `new_id` */
+	struct wl_array *a;  /**< `array`  */
+	int32_t h;           /**< `fd`     */
 };

 /**
--
2.7.2