[PATCH wayland v2] util: Clarify documentation of wl_dispatcher_func_t

[Yong Bakos]

Hi Daniel,

> On Nov 21, 2016, at 9:14 AM, Daniel Stone <daniel at fooishbar.org> wrote:
> 
> Hi Yong,
> 
> On 21 November 2016 at 13:44, Yong Bakos <junk at humanoriented.com> wrote:
>> - * 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.
> 
> I think removing the final word 'the dispatcher-specific
> implementation data' is a loss of precision/accuracy. If you don't
> mind reinstating that final word, I'll merge with my R-b.

I have no problem with this. The reason why I changed it from "implementation data"
to just "implementation" is because wl_closure_dispatch[1] passes an implementation
as the first argument. I assumed this use was the specific intent, making the
description vague; but perhaps this is just one intent, and the description should
be more general ("implementation data").

I'm fine either way (you know waaaay better than I do).

Thank you,
yong

[1] connection.c:939:

void
wl_closure_dispatch(struct wl_closure *closure, wl_dispatcher_func_t dispatcher,
		    struct wl_object *target, uint32_t opcode)
{
	dispatcher(target->implementation, target, opcode, closure->message,
		   closure->args);
}



> 
> Cheers,
> Daniel
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel