[PATCH libinput 4/6] doc: add the various events to the doxygen groups

[Jon A. Cruz]

On 12/09/2014 04:34 PM, Peter Hutterer wrote:
> Makes them show up on the respective page and in the data structures list
> doxygen generates.
> 
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
>  src/libinput.h | 29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
> 
> diff --git a/src/libinput.h b/src/libinput.h
> index 682e16f..d6e0446 100644
> --- a/src/libinput.h
> +++ b/src/libinput.h
> @@ -306,9 +306,38 @@ struct libinput;
>  struct libinput_device;
>  struct libinput_seat;
>  
> +/**
> + * @ingroup event
> + * @struct libinput_event
> + *
> + * The base event type. Use libinput_event_get_pointer_event() or similar to
> + * get the actual event type.
> + */
>  struct libinput_event;
...


The @struct tag should really not be required. One of the better ways to
use Doxygen is to use the more modern Javadoc approach and not the
outdated Trolltech one.

Specific to that point is adding the doc comment just before the thing
being commented. It makes the explicit tag redundant. It also prevents
issues with typos or of comments getting out of sync.

A second aspect of that less-is-more approach is to start with a single
sentence that also happens to be the brief description. Thus I'd believe
it would be better to place @ingroup at the end of the comment if possible.