[PATCH wayland] util: Clarify documentation of wl_dispatcher_func_t

[Yong Bakos]

Verified that the intent of the return type of wl_dispatcher_func_t is
for an error code. I'm including a response from J Ekstrand, author
of wl_dispatcher_func_t inline below, for the record.

> On Nov 17, 2016, at 8:28 AM, Yong Bakos <junk at humanoriented.com> wrote:
> 
> 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

Here...

>> Begin forwarded message:
>> 
>> From: Jason Ekstrand <...>
>> Subject: Re: [PATCH wayland] util: Clarify documentation of wl_dispatcher_func_t
>> Date: November 20, 2016 at 7:39:04 PM PST
>> To: Yong Bakos <...>
>> 
>> On Sat, Nov 19, 2016 at 10:55 PM, Yong Bakos <...> wrote:
>>> Hi Jason,
>>> I've been working on documentation for Wayland and was wondering if you
>>> might be able to tell me what the intent for the `int` return value of
>>> wl_dispatcher_func_t is for?
>> 
>> First off, I should say that any answers I give are from a very rusty memory.  It's been about 4 years since I worked on that.  I believe the intention (which may not have been fully implemented) was for error handling.  If the dispatcher had an error, it would get propagated up and returned out of the event loop dispatch function.  Ideally, if working with a higher-level language such as Java or Python, an exception would get turned into an error and then back to an exception thrown from the language-wrapped queue dispatch function.  That was the intention but I'm not sure if it ever worked quite as well as all that.  It's entirely possible that libwayland simply ignores it which would make it useless.
>> 
>> --Jason
>>  
>>> Thank you,
>>> yong
>>> 
>>> typedef int (*wl_dispatcher_func_t)(const void *, void *, uint32_t, ...
>> 

Will send a v2 with the return type amendment.

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