[Spice-devel] [PATCH 2/5] DisplayChannel: add documentation for Ring types

[Frediano Ziglio]

> 
> The Surface and Display channels each have a 'current_list' Ring, and
> Surface also has a 'current' Ring. these names are confusing, so at
> minimum, add a comment indicating the type of object they hold. The
> DisplayChannel::current_list already had a comment, but it was
> incorrect.
> ---
>  server/display-channel-private.h | 6 +++++-
>  server/display-channel.h         | 6 ++++++
>  2 files changed, 11 insertions(+), 1 deletion(-)
> 
> diff --git a/server/display-channel-private.h
> b/server/display-channel-private.h
> index afb28b6..a727ddb 100644
> --- a/server/display-channel-private.h
> +++ b/server/display-channel-private.h
> @@ -41,7 +41,11 @@ struct DisplayChannelPrivate
>      int enable_jpeg;
>      int enable_zlib_glz_wrap;
>  
> -    Ring current_list; // of TreeItem
> +    /* A ring of pending drawables for this DisplayChannel, regardless of
> which
> +     * surface they're associated with. This list is mainly used to flush
> older
> +     * drawables when we need to make room for new drawables.  The ring is
> +     * maintained in order of age, the tail being the oldest drawable */
> +    Ring current_list;
>  
>      uint32_t drawable_count;
>      _Drawable drawables[NUM_DRAWABLES];
> diff --git a/server/display-channel.h b/server/display-channel.h
> index 497f911..5c14017 100644
> --- a/server/display-channel.h
> +++ b/server/display-channel.h
> @@ -162,7 +162,13 @@ typedef struct DrawContext {
>  
>  typedef struct RedSurface {
>      uint32_t refs;
> +    /* A Ring representing a hierarchical tree structure. This tree includes
> +     * DrawItems, Containers, and Shadows. It is used to efficiently
> determine
> +     * which drawables overlap, and to exclude regions of drawables that are
> +     * obscured by other drawables */
>      Ring current;
> +    /* A ring of pending Drawables associated with this surface. This ring
> is
> +     * actually used for drawing */

I would add the same sentence:

"The ring is maintained in order of age, the tail being the oldest drawable."

even for this field.

>      Ring current_list;
>      DrawContext context;
>  

Beside that patch looks fine to me.

Frediano