[PATCH 10/21] docs: Improve wl_shm and wl_shm_pool protocol docs

[Jason Ekstrand]

On Sat, Mar 30, 2013 at 12:11 AM,  <matthias.clasen at gmail.com> wrote:
> From: Matthias Clasen <mclasen at redhat.com>
>
> Reword some paragraphs, and spell out 'file descriptor'.
> ---
>  protocol/wayland.xml | 73 +++++++++++++++++++++++++++++++++++-----------------
>  1 file changed, 49 insertions(+), 24 deletions(-)
>
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index cc009eb..31d7ce8 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -196,20 +196,21 @@
>        The wl_shm_pool object encapsulates a piece of memory shared
>        between the compositor and client.  Through the wl_shm_pool
>        object, the client can allocate shared memory wl_buffer objects.
> -      The objects will share the same underlying mapped memory.
> -      Reusing the mapped memory avoids the setup/teardown overhead and
> -      is useful when interactively resizing a surface or for many
> -      small buffers.
> +      All objects created through the same pool share the same
> +      underlying mapped memory. Reusing the mapped memory avoids the
> +      setup/teardown overhead and is useful when interactively resizing
> +      a surface or for many small buffers.

Perhaps "All wl_buffer objects" would be better

>      </description>
>
>      <request name="create_buffer">
> -      <description summary="create wl_buffer from pool">
> -       Create a wl_buffer from the pool.  The buffer is created a
> -       offset bytes into the pool and has width and height as
> -       specified.  The stride arguments specifies the number of bytes
> -       from beginning of one row to the beginning of the next.  The
> -       format is the pixel format of the buffer and must be one of
> -       those advertised through the wl_shm.format event.
> +      <description summary="create a buffer from the pool">
> +       Create a wl_buffer object from the pool.

Should go in summary

> +
> +       The buffer is created offset bytes into the pool and has
> +       width and height as specified.  The stride arguments specifies
> +       the number of bytes from beginning of one row to the beginning
> +       of the next.  The format is the pixel format of the buffer and
> +       must be one of those advertised through the wl_shm.format event.
>
>         A buffer will keep a reference to the pool it was created from
>         so it is valid to destroy the pool immediately after creating
> @@ -226,15 +227,19 @@
>
>      <request name="destroy" type="destructor">
>        <description summary="destroy the pool">
> -       Destroy the pool.
> +       Destroy the shared memory pool.
Summary

> +
> +       The mmapped memory will be released when all
> +       buffers that have been created from this pool
> +       are gone.
>        </description>
>      </request>
>
>      <request name="resize">
>        <description summary="change the size of the pool mapping">
>         This request will cause the server to remap the backing memory
> -       for the pool from the fd passed when the pool was creating but
> -       using the new size.
> +       for the pool from the file descriptor passed when the pool was
> +       created, but using the new size.
>        </description>
>
>        <arg name="size" type="int"/>
> @@ -243,26 +248,41 @@
>
>    <interface name="wl_shm" version="1">
>      <description summary="shared memory support">
> -      Support for shared memory buffers.
> +      A global singleton object that provides support for shared
> +      memory.
> +
> +      Clients can create wl_shm_pool objects using the create_pool
> +      request.
> +
> +      At connection setup time, the wl_shm object emits one or more
> +      format events to inform clients about the valid pixel formats
> +      that can be used for buffers.
>      </description>
>
>      <enum name="error">
> -      <entry name="invalid_format" value="0"/>
> -      <entry name="invalid_stride" value="1"/>
> -      <entry name="invalid_fd" value="2"/>
> +      <description summary="wl_shm error values">
> +       These errors can be emitted in response to wl_shm requests.
> +      </description>
> +      <entry name="invalid_format" value="0" summary="buffer format is not known"/>
> +      <entry name="invalid_stride" value="1" summary="invalid size or stride during pool or buffer creation"/>
> +      <entry name="invalid_fd" value="2" summary="mmapping the file descriptor failed"/>
>      </enum>
>
>      <enum name="format">
> -      <entry name="argb8888" value="0"/>
> -      <entry name="xrgb8888" value="1"/>
> +      <description summary="pixel formats">
> +       This describes the memory layout of an individual pixel.
> +      </description>
> +      <entry name="argb8888" value="0" summary="32-bit ARGB format"/>
> +      <entry name="xrgb8888" value="1" summary="32-bit RGB format"/>
>      </enum>
>
>      <request name="create_pool">
>        <description summary="create a shm pool">
> -       This creates wl_shm_pool object, which can be used to create
> -       shared memory based wl_buffer objects.  The server will mmap
> -       size bytes of the passed fd, to use as backing memory for then
> -       pool.
> +       Create a new wl_shm_pool object.

summary

> +
> +       The pool can be used to create shared memory based buffer
> +       objects.  The server will mmap size bytes of the passed file
> +        descriptor, to use as backing memory for the pool.
>        </description>
>
>        <arg name="id" type="new_id" interface="wl_shm_pool"/>
> @@ -271,6 +291,11 @@
>      </request>
>
>      <event name="format">
> +      <description summary="pixel format description">
> +       Informs the client about a valid pixel format that
> +       can be used for buffers. Known formats include
> +       argb8888 and xrgb8888.

We don't want to put known formats here.  Those will be documented in
the formats enum.  Documenting them here only makes for more
documentation to keep up-to-date.

> +      </description>
>        <arg name="format" type="uint"/>
>      </event>
>    </interface>
> --
> 1.8.1.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel