[PATCH wayland] util: Clarify documentation of wl_dispatcher_func_t

[Yong Bakos]

On Nov 17, 2016, at 8:23 AM, Yong Bakos <junk at humanoriented.com> wrote:
> 
> From: Yong Bakos <ybakos at humanoriented.com>
> 
> Adjust the brief, clarify the behavior and arguments, correct a grammar
> error, and document the parameters.
> 
> Signed-off-by: Yong Bakos <ybakos at humanoriented.com>

Eh - what is the int return value for?
connection.c doesn't use it when invoking a wl_dispatcher_func_t.

yong


> ---
> src/wayland-util.h | 25 +++++++++++++++----------
> 1 file changed, 15 insertions(+), 10 deletions(-)
> 
> diff --git a/src/wayland-util.h b/src/wayland-util.h
> index 50f3372..17908fd 100644
> --- a/src/wayland-util.h
> +++ b/src/wayland-util.h
> @@ -607,21 +607,26 @@ union wl_argument {
> };
> 
> /**
> - * \brief A function pointer type for a dispatcher.
> + * Dispatcher function type alias
>  *
>  * A dispatcher is a function that handles the emitting of callbacks in client
> - * code.  For programs directly using the C library, this is done by using
> - * libffi to call function pointers.  When binding to languages other than C,
> + * code. For programs directly using the C library, this is done by using
> + * libffi to call function pointers. When binding to languages other than C,
>  * dispatchers provide a way to abstract the function calling process to be
>  * friendlier to other function calling systems.
>  *
> - * A dispatcher takes five arguments:  The first is the dispatcher-specific
> - * implementation data associated with the target object.  The second is the
> - * object on which the callback is being invoked (either wl_proxy or
> - * wl_resource).  The third and fourth arguments are the opcode the wl_message
> - * structure corresponding to the callback being emitted.  The final argument
> - * is an array of arguments received from the other process via the wire
> - * protocol.
> + * A dispatcher takes five arguments: The first is the dispatcher-specific
> + * implementation associated with the target object. The second is the object
> + * upon which the callback is being invoked (either wl_proxy or wl_resource).
> + * The third and fourth arguments are the opcode and the wl_message
> + * corresponding to the callback. The final argument is an array of arguments
> + * received from the other process via the wire protocol.
> + *
> + * \param "const void *" Dispatcher-specific implementation data
> + * \param "void *" Callback invocation target (wl_proxy or `wl_resource`)
> + * \param uint32_t Callback opcode
> + * \param "const struct wl_message *" Callback message signature
> + * \param "union wl_argument *" Array of received arguments
>  */
> typedef int (*wl_dispatcher_func_t)(const void *, void *, uint32_t,
> 				    const struct wl_message *,
> -- 
> 2.7.2
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel