protocol: Add summaries to event parameters

All event arg elements now have an appropriate summary attribute.
This was conducted mostly in response to the undocumented parameter
warnings generated during 'make check'.

Signed-off-by: Yong Bakos <ybakos@humanoriented.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 378879e..1555677 100644 (file)
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -70,9 +70,9 @@
        own set of error codes.  The message is a brief description
        of the error, for (debugging) convenience.
       </description>
-      <arg name="object_id" type="object"/>
-      <arg name="code" type="uint"/>
-      <arg name="message" type="string"/>
+      <arg name="object_id" type="object" summary="object where the error occurred"/>
+      <arg name="code" type="uint" summary="error code"/>
+      <arg name="message" type="string" summary="error description"/>
     </event>
 
     <enum name="error">
@@ -96,7 +96,7 @@
        When the client receives this event, it will know that it can
        safely reuse the object ID.
       </description>
-      <arg name="id" type="uint" />
+      <arg name="id" type="uint" summary="deleted object id"/>
     </event>
   </interface>
 
@@ -141,9 +141,9 @@
         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"/>
-      <arg name="version" type="uint"/>
+      <arg name="name" type="uint" summary="numeric name of the global object"/>
+      <arg name="interface" type="string" summary="interface implemented by the object"/>
+      <arg name="version" type="uint" summary="interface version"/>
     </event>
 
     <event name="global_remove">
@@ -159,7 +159,7 @@
        ignored until the client destroys it, to avoid races between
        the global going away and a client sending a request to it.
       </description>
-      <arg name="name" type="uint"/>
+      <arg name="name" type="uint" summary="numeric name of the global object"/>
     </event>
   </interface>
 
@@ -367,7 +367,7 @@
        can be used for buffers. Known formats include
        argb8888 and xrgb8888.
       </description>
-      <arg name="format" type="uint" enum="format"/>
+      <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
     </event>
   </interface>
 
@@ -485,7 +485,7 @@
        event per offered mime type.
       </description>
 
-      <arg name="mime_type" type="string"/>
+      <arg name="mime_type" type="string" summary="offered mime type"/>
     </event>
 
     <!-- Version 3 additions -->
@@ -550,7 +550,7 @@
        will be sent right after wl_data_device.enter, or anytime the source
        side changes its offered actions through wl_data_source.set_actions.
       </description>
-      <arg name="source_actions" type="uint"/>
+      <arg name="source_actions" type="uint" summary="actions offered by the data source"/>
     </event>
 
     <event name="action" since="3">
@@ -591,7 +591,7 @@
        final wl_data_offer.set_actions and wl_data_offer.accept requests
        must happen before the call to wl_data_offer.finish.
       </description>
-      <arg name="dnd_action" type="uint"/>
+      <arg name="dnd_action" type="uint" summary="action selected by the compositor"/>
     </event>
   </interface>
 
@@ -633,7 +633,7 @@
        Used for feedback during drag-and-drop.
       </description>
 
-      <arg name="mime_type" type="string" allow-null="true"/>
+      <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the target"/>
     </event>
 
     <event name="send">
@@ -643,8 +643,8 @@
        close it.
       </description>
 
-      <arg name="mime_type" type="string"/>
-      <arg name="fd" type="fd"/>
+      <arg name="mime_type" type="string" summary="mime type for the data"/>
+      <arg name="fd" type="fd" summary="file descriptor for the data"/>
     </event>
 
     <event name="cancelled">
@@ -746,7 +746,7 @@
        Clients can trigger cursor surface changes from this point, so
        they reflect the current action.
       </description>
-      <arg name="dnd_action" type="uint"/>
+      <arg name="dnd_action" type="uint" summary="action selected by the compositor"/>
     </event>
   </interface>
 
@@ -821,7 +821,7 @@
        mime types it offers.
       </description>
 
-      <arg name="id" type="new_id" interface="wl_data_offer"/>
+      <arg name="id" type="new_id" interface="wl_data_offer" summary="the new data_offer object"/>
     </event>
 
     <event name="enter">
@@ -832,11 +832,12 @@
        coordinates.
       </description>
 
-      <arg name="serial" type="uint"/>
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="x" type="fixed"/>
-      <arg name="y" type="fixed"/>
-      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"/>
+      <arg name="serial" type="uint" summary="serial number of the enter event"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="client surface entered"/>
+      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
+      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
+      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
+          summary="source data_offer object"/>
     </event>
 
     <event name="leave">
@@ -855,8 +856,8 @@
        coordinates.
       </description>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
-      <arg name="x" type="fixed"/>
-      <arg name="y" type="fixed"/>
+      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
+      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
     </event>
 
     <event name="drop">
@@ -891,7 +892,8 @@
        destroy the previous selection data_offer, if any, upon receiving
        this event.
       </description>
-      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"/>
+      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
+          summary="selection data_offer object"/>
     </event>
 
     <!-- Version 2 additions -->
@@ -1230,7 +1232,7 @@
        Ping a client to check if it is receiving events and sending
        requests. A client is expected to reply with a pong request.
       </description>
-      <arg name="serial" type="uint"/>
+      <arg name="serial" type="uint" summary="serial number of the ping"/>
     </event>
 
     <event name="configure">
@@ -1254,9 +1256,9 @@
        in surface-local coordinates.
       </description>
 
-      <arg name="edges" type="uint" enum="resize"/>
-      <arg name="width" type="int"/>
-      <arg name="height" type="int"/>
+      <arg name="edges" type="uint" enum="resize" summary="how the surface was resized"/>
+      <arg name="width" type="int" summary="new width of the surface"/>
+      <arg name="height" type="int" summary="new height of the surface"/>
     </event>
 
     <event name="popup_done">
@@ -1532,7 +1534,7 @@
 
        Note that a surface may be overlapping with zero or more outputs.
       </description>
-      <arg name="output" type="object" interface="wl_output"/>
+      <arg name="output" type="object" interface="wl_output" summary="output entered by the surface"/>
     </event>
 
     <event name="leave">
@@ -1541,7 +1543,7 @@
        results in it no longer having any part of it within the scanout region
        of an output.
       </description>
-      <arg name="output" type="object" interface="wl_output"/>
+      <arg name="output" type="object" interface="wl_output" summary="output left by the surface"/>
     </event>
 
     <!-- Version 2 additions -->
@@ -1700,7 +1702,7 @@
        The above behavior also applies to wl_keyboard and wl_touch with the
        keyboard and touch capabilities, respectively.
       </description>
-      <arg name="capabilities" type="uint" enum="capability"/>
+      <arg name="capabilities" type="uint" enum="capability" summary="capabilities of the seat"/>
     </event>
 
     <request name="get_pointer">
@@ -1750,7 +1752,7 @@
        identify which physical devices the seat represents. Based on
        the seat configuration used by the compositor.
       </description>
-      <arg name="name" type="string"/>
+      <arg name="name" type="string" summary="seat identifier"/>
     </event>
 
     <!-- Version 5 additions -->
@@ -1831,8 +1833,8 @@
        an appropriate pointer image with the set_cursor request.
       </description>
 
-      <arg name="serial" type="uint"/>
-      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="serial" type="uint" summary="serial number of the enter event"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="surface entered by the pointer"/>
       <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
       <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
     </event>
@@ -1845,8 +1847,8 @@
        The leave notification is sent before the enter notification
        for the new focus.
       </description>
-      <arg name="serial" type="uint"/>
-      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="serial" type="uint" summary="serial number of the leave event"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="surface left by the pointer"/>
     </event>
 
     <event name="motion">
@@ -1880,10 +1882,10 @@
         granularity, with an undefined base.
       </description>
 
-      <arg name="serial" type="uint"/>
+      <arg name="serial" type="uint" summary="serial number of the button event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
-      <arg name="button" type="uint"/>
-      <arg name="state" type="uint" enum="button_state"/>
+      <arg name="button" type="uint" summary="button that produced the event"/>
+      <arg name="state" type="uint" enum="button_state" summary="physical state of the button"/>
     </event>
 
     <enum name="axis">
@@ -1915,8 +1917,8 @@
       </description>
 
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
-      <arg name="axis" type="uint" enum="axis"/>
-      <arg name="value" type="fixed"/>
+      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
+      <arg name="value" type="fixed" summary="length of vector in surface-local coordinate space"/>
     </event>
 
     <!-- Version 3 additions -->
@@ -2019,7 +2021,7 @@
        The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
        not guaranteed.
       </description>
-      <arg name="axis_source" type="uint" enum="axis_source"/>
+      <arg name="axis_source" type="uint" enum="axis_source" summary="source of the axis event"/>
     </event>
 
     <event name="axis_stop" since="5">
@@ -2072,8 +2074,8 @@
        The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
        not guaranteed.
       </description>
-      <arg name="axis" type="uint" enum="axis" />
-      <arg name="discrete" type="int"/>
+      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
+      <arg name="discrete" type="int" summary="number of steps"/>
     </event>
   </interface>
 
@@ -2099,9 +2101,9 @@
        This event provides a file descriptor to the client which can be
        memory-mapped to provide a keyboard mapping description.
       </description>
-      <arg name="format" type="uint" enum="keymap_format"/>
-      <arg name="fd" type="fd"/>
-      <arg name="size" type="uint"/>
+      <arg name="format" type="uint" enum="keymap_format" summary="keymap format"/>
+      <arg name="fd" type="fd" summary="keymap file descriptor"/>
+      <arg name="size" type="uint" summary="keymap size, in bytes"/>
     </event>
 
     <event name="enter">
@@ -2109,8 +2111,8 @@
        Notification that this seat's keyboard focus is on a certain
        surface.
       </description>
-      <arg name="serial" type="uint"/>
-      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="serial" type="uint" summary="serial number of the enter event"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="surface gaining keyboard focus"/>
       <arg name="keys" type="array" summary="the currently pressed keys"/>
     </event>
 
@@ -2122,8 +2124,8 @@
        The leave notification is sent before the enter notification
        for the new focus.
       </description>
-      <arg name="serial" type="uint"/>
-      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="serial" type="uint" summary="serial number of the leave event"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="surface that lost keyboard focus"/>
     </event>
 
     <enum name="key_state">
@@ -2141,10 +2143,10 @@
         granularity, with an undefined base.
       </description>
 
-      <arg name="serial" type="uint"/>
+      <arg name="serial" type="uint" summary="serial number of the key event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
-      <arg name="key" type="uint"/>
-      <arg name="state" type="uint" enum="key_state"/>
+      <arg name="key" type="uint" summary="key that produced the event"/>
+      <arg name="state" type="uint" enum="key_state" summary="physical state of the key"/>
     </event>
 
     <event name="modifiers">
@@ -2153,11 +2155,11 @@
        changed, and it should update its local state.
       </description>
 
-      <arg name="serial" type="uint"/>
-      <arg name="mods_depressed" type="uint"/>
-      <arg name="mods_latched" type="uint"/>
-      <arg name="mods_locked" type="uint"/>
-      <arg name="group" type="uint"/>
+      <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
+      <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
+      <arg name="mods_latched" type="uint" summary="latched modifiers"/>
+      <arg name="mods_locked" type="uint" summary="locked modifiers"/>
+      <arg name="group" type="uint" summary="keyboard layout"/>
     </event>
 
     <!-- Version 3 additions -->
@@ -2210,9 +2212,9 @@
        this ID. The ID ceases to be valid after a touch up event and may be
        reused in the future.
       </description>
-      <arg name="serial" type="uint"/>
+      <arg name="serial" type="uint" summary="serial number of the touch down event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
-      <arg name="surface" type="object" interface="wl_surface"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="surface touched"/>
       <arg name="id" type="int" summary="the unique ID of this touch point"/>
       <arg name="x" type="fixed" summary="surface-local x coordinate"/>
       <arg name="y" type="fixed" summary="surface-local y coordinate"/>
@@ -2224,7 +2226,7 @@
        this touch point and the touch point's ID is released and may be
        reused in a future touch down event.
       </description>
-      <arg name="serial" type="uint"/>
+      <arg name="serial" type="uint" summary="serial number of the touch up event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
       <arg name="id" type="int" summary="the unique ID of this touch point"/>
     </event>