[PATCH libinput 6/6] doc: put some extra warning in for libinput_event_destroy()

[Jonas Ådahl]

Hi,

Comment inline.

On Wed, Dec 10, 2014 at 10:34:04AM +1000, Peter Hutterer wrote:
> Unlike all other structs, events aren't refcounted and will get destroyed
> immediately.
> 
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
>  src/libinput.h | 10 +++++++++-
>  1 file changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/src/libinput.h b/src/libinput.h
> index 7e5d93c..f7cb169 100644
> --- a/src/libinput.h
> +++ b/src/libinput.h
> @@ -335,6 +335,9 @@ struct libinput_seat;
>   *
>   * The base event type. Use libinput_event_get_pointer_event() or similar to
>   * get the actual event type.
> + *
> + * @warning Unlike other structs events are considered transient and
> + * <b>not</b> refcounted.
>   */
>  struct libinput_event;
>  
> @@ -382,7 +385,12 @@ struct libinput_event_touch;
>  /**
>   * @ingroup event
>   *
> - * Destroy the event.
> + * Destroy the event, freeing all associated data. Data obtained from this
> + * event must be considered invalid after this call.

Hmm. Is this really correct? The validity of some data, for example the
coordnates of an absolute motion event, is not related to the lifetime
of the event, but should rather be considered invalid after some (very
short) time, so saying that an event invalidates all data of an event
doesn't seem to make sense to me. What it does invalidate would be any
data accessed via a pointer, so maybe that is what should be written
instead?

> + *
> + * @warning Unlike other structs events are considered transient and
> + * <b>not</b> refcounted. Calling libinput_event_destroy() <b>will</b>
> + * destroy the event.
>   *
>   * @param event An event retrieved by libinput_get_event().
>   */
> -- 
> 2.1.0

Jonas