[PATCH wayland] util: Clarify documentation of wl_dispatcher_func_t

[Bryce Harrington]

On Thu, Nov 17, 2016 at 08:23:14AM -0800, Yong Bakos 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>

Definitely an improvement.  The brief still feels a bit heavy on jargon
but it's better than the original.

Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>

> ---
>  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