[PATCH 07/21] docs: Improve wl_display 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>
>
> This adds a bit of information about in-order event delivery,
> removes extraneous formatting, and adds a missing period.
> ---
>  protocol/wayland.xml | 17 +++++++++--------
>  1 file changed, 9 insertions(+), 8 deletions(-)
>
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 9d276f8..8587b8f 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -36,9 +36,10 @@
>      <request name="sync">
>        <description summary="asynchronous roundtrip">
>         The sync request asks the server to emit the 'done' event
> -       on the provided wl_callback object.  Since requests are
> -       handled in-order, this can be used as a barrier to ensure all
> -       previous requests have been handled.
> +       on the returned wl_callback object.  Since requests are
> +       handled in-order and events are delivered in-order, this can
> +       used as a barrier to ensure all previous requests and the
> +       resulting events have been handled.

Actually, the original is more correct.  First, the callback is
provided the the server not returned by the server.  It looks like
it's returned because libwayland does some magic there.  However, it
is reasonable to think of it in terms of the client giving the server
a callback to fire.  Also, while events are delivered to the socket in
order, they may not be handled by the client in-order.  If the client
wants to use a sync event to guarantee they have gotten a certain
event (the way it's usually used), they need to make sure that the
sync callback event and that event will be handled by the same event
queue.

>        </description>
>        <arg name="callback" type="new_id" interface="wl_callback"/>
>      </request>
> @@ -55,11 +56,11 @@
>      <event name="error">
>        <description summary="fatal error event">
>         The error event is sent out when a fatal (non-recoverable)
> -       error has occurred.  The @object_id argument is the object
> +       error has occurred.  The object_id argument is the object
>         where the error occurred, most often in response to a request
> -       to that object.  The @code identifies the error and is defined
> +       to that object.  The code identifies the error and is defined
>         by the object interface.  As such, each interface defines its
> -       own set of error codes.  The @message is an brief description
> +       own set of error codes.  The message is an brief description
>         of the error, for (debugging) convenience.
>        </description>

Someone can correct me if I'm wrong, but I'm pretty sure we want to
leave the "@" characters in here.  When the protocol file is used to
generate in-code documentation such as javadoc or doxygen comments,
API documentation tool (doxygen or javadoc) will pick up on those and
hyperlink them.  That said, perhaps we want to have some sort of
in-documentation flag such as <event>, <request>, and <enum> that
would indicate that.  I think we should better decide how we want to
handle this before we go through and remove all of the "@"s

All that being said, a better solution in this particular case would
be to move those comments to the "summary" argument of the <arg> tag.
Take a look at some of the other events/requests in the protocol and
you'll see what I mean.

>        <arg name="object_id" type="object"/>
> @@ -81,12 +82,12 @@
>      </enum>
>
>      <event name="delete_id">
> -      <description summary="acknowledge object id deletion">
> +      <description summary="acknowledge object ID deletion">
>         This event is used internally by the object ID management
>         logic.  When a client deletes an object, the server will send
>         this event to acknowledge that it has seen the delete request.
>         When the client receive this event, it will know that it can
> -       safely reuse the object ID
> +       safely reuse the object ID.
>        </description>
>        <arg name="id" type="uint" />
>      </event>
> --
> 1.8.1.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel