[PATCH 08/21] docs: Improve the wl_registry 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 a few things, and add some details.
> ---
>  protocol/wayland.xml | 44 ++++++++++++++++++++++++++------------------
>  1 file changed, 26 insertions(+), 18 deletions(-)
>
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 8587b8f..ad72fd1 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -98,36 +98,41 @@
>        The global registry object.  The server has a number of global
>        objects that are available to all clients.  These objects
>        typically represent an actual object in the server (for example,
> -      an input device) or they are singleton objects that provides
> +      an input device) or they are singleton objects that provide
>        extension functionality.
>
>        When a client creates a registry object, the registry object
>        will emit a global event for each global currently in the
> -      registry.  Globals come and go as a result of device hotplugs,
> -      reconfiguration or other events, and the registry will send out
> -      @global and @global_remove events to keep the client up to date
> -      with the changes.  To mark the end of the initial burst of
> -      events, the client can use the wl_display.sync request
> -      immediately after calling wl_display.get_registry.
> -
> -      A client can 'bind' to a global object by using the bind
> -      request.  This creates a client side handle that lets the object
> +      registry.  Globals come and go as a result of device or
> +      monitor hotplugs, reconfiguration or other events, and the
> +      registry will send out global and global_remove events to
> +      keep the client up to date with the changes.  To mark the end
> +      of the initial burst of events, the client can use the
> +      wl_display.sync request immediately after calling
> +      wl_display.get_registry.

Again, I think there's a better solution than simply removing the "@"
characters.

> +
> +      A client can bind to a global object by using the bind
> +      request.  This creates a client-side handle that lets the object
>        emit events to the client and lets the client invoke requests on
>        the object.
>      </description>
>
>      <request name="bind">
>        <description summary="bind an object to the display">
> -       Binds a new, client-created object to the server using @name as
> -       the identifier.
> +       Binds a new, client-created object to the server using the
> +        specified name as the identifier.
>        </description>
> -      <arg name="name" type="uint" summary="unique number id for object"/>
> +      <arg name="name" type="uint" summary="unique name for the object"/>
>        <arg name="id" type="new_id"/>
>      </request>
>
>      <event name="global">
>        <description summary="announce global object">
> -       Notify the client of global objects.
> +       Notify the client of global objects.

The first line should go in the summary

> +
> +        The event notifies the client that a global object with
> +        the given name is now available, and it implements the
> +        given version of the given interface.
>        </description>
>        <arg name="name" type="uint"/>
>        <arg name="interface" type="string"/>
> @@ -136,10 +141,13 @@
>
>      <event name="global_remove">
>        <description summary="announce removal of global object">
> -       Notify the client of removed global objects.  This event
> -       notifies the client that the global identifies by @name is no
> -       longer available.  If the client bound to the global using the
> -       'bind' request, the client should now destroy that object.
> +       Notify the client of removed global objects.

Again, the first line belongs in summary

> +
> +        This event notifies the client that the global identified
> +        by name is no longer available.  If the client bound to
> +        the global using the bind request, the client should now
> +        destroy that object.
> +
>         The object remains valid and requests to the object will be
>         ignored until the client destroys it, to avoid races between
>         the global going away and a client sending a request to it.
> --
> 1.8.1.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel