Re: [PATCH wayland v2] util: Clarify documentation of wl_dispatcher_func_t
Hi,
On 21 November 2016 at 20:59, Yong Bakos wrote:
> On Nov 21, 2016, at 9:14 AM, Daniel Stone wrote:
>> 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 wy better than I do).
OK, fair enough! Pushed in its original form, thanks:
To ssh://git.freedesktop.org/git/wayland/wayland
a26ed09..0242007 master -> master
Cheers,
Daniel
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland v2] util: Clarify documentation of wl_dispatcher_func_t
Hi Daniel,
> On Nov 21, 2016, at 9:14 AM, Daniel Stone wrote:
>
> Hi Yong,
>
> On 21 November 2016 at 13:44, Yong Bakos 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 wy 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@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH wayland v2] util: Clarify documentation of wl_dispatcher_func_t
Hi Yong, On 21 November 2016 at 13:44, Yong Bakos 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. Cheers, Daniel ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
[PATCH wayland v2] util: Clarify documentation of wl_dispatcher_func_t
From: Yong Bakos
Adjust the brief, clarify the behavior and arguments, correct a grammar
error, document the parameters, and document the return type.
Signed-off-by: Yong Bakos
Reviewed-by: Bryce Harrington
---
v2: Document intent of return type.
src/wayland-util.h | 27 +--
1 file changed, 17 insertions(+), 10 deletions(-)
diff --git a/src/wayland-util.h b/src/wayland-util.h
index 170bf86..f0a4508 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -662,21 +662,28 @@ 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
+ *
+ * \return 0 on success, or -1 on failure
*/
typedef int (*wl_dispatcher_func_t)(const void *, void *, uint32_t,
const struct wl_message *,
--
2.7.2
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
