[Spice-devel] [PATCH v2] add some comments to cursor-channel.h header

[Jonathon Jongsma]

On Thu, 2016-05-26 at 18:47 +0100, Frediano Ziglio wrote:
> Explain usage of the class.
> 
> Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
> ---
>  server/cursor-channel.h | 34 +++++++++++++++++++++++++++++++++-
>  1 file changed, 33 insertions(+), 1 deletion(-)
> 
> I'm not sure I should add Jonathon name to the patch
> as the biggest comments was mainly written by him...
> 
> diff --git a/server/cursor-channel.h b/server/cursor-channel.h
> index 6c89bc3..84592db 100644
> --- a/server/cursor-channel.h
> +++ b/server/cursor-channel.h
> @@ -23,20 +23,52 @@
>  #include "red-worker.h"
>  #include "red-parse-qxl.h"
>  
> +/**
> + * This type it's a RedChannel class which implement cursor (mouse)
> + * movements.
> + * A pointer to CursorChannel can be converted to a RedChannel.
> + */
>  typedef struct CursorChannel CursorChannel;
>  
> +/**
> + * Create CursorChannel.
> + * Since CursorChannel is intended to be run in a separate thread,
> + * it does not register its own client callbacks since they would
> + * be called from a different thread. Therefore users of this
> + * class are responsible for registering their own client callbacks
> + * for CursorChannel. These 'wrapper' client callbacks must forward
> + * execution on to the CursorChannel thread.
> + * cursor_channel_client_migrate() and cursor_channel_connect() are
> + * provided as helper functions and should only be called from the
> + * CursorChannel thread.
> + */
>  CursorChannel*       cursor_channel_new         (RedWorker *worker);
> -void                 cursor_channel_disconnect  (CursorChannel
> *cursor_channel);
> +
> +/**
> + * Cause the channel to disconnect all clients
> + */
> +void                 cursor_channel_disconnect  (CursorChannel *cursor);
>  void                 cursor_channel_reset       (CursorChannel *cursor);
>  void                 cursor_channel_init        (CursorChannel *cursor);
>  void                 cursor_channel_process_cmd (CursorChannel *cursor,
> RedCursorCmd *cursor_cmd);
>  void                 cursor_channel_set_mouse_mode(CursorChannel *cursor,
> uint32_t mode);
> +
> +/**
> + * Connect a new client to CursorChannel.
> + * This is the equivalent of ReChannel client connect callback.

ReChannel -> RedChannel

> + * See comment on cursor_channel_new.
> + */
>  void                 cursor_channel_connect     (CursorChannel *cursor,
> RedClient *client, 
>                                                   RedsStream *stream,
>                                                   int migrate,
>                                                   uint32_t *common_caps, int
> num_common_caps,
>                                                   uint32_t *caps, int
> num_caps);
>  
> +/**
> + * Migrate a client channel from a CursorChannel.
> + * This is the equivalent of ReChannel client migrate callback.

same as above

> + * See comment on cursor_channel_new.
> + */
>  void                 cursor_channel_client_migrate(RedChannelClient *client);
>  
>  #endif /* CURSOR_CHANNEL_H_ */


aside from the typos mentioned, ACK

Acked-by: Jonathon Jongsma <jjongsma at redhat.com>