[PATCH wayland v3] util: Improve documentation of wl_argument

[Peter Hutterer]

On Sat, Nov 12, 2016 at 10:11:21AM -0800, Yong Bakos wrote:
> 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>

Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>

Cheers,
   Peter

> ---
> 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
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
>