On Fri, Apr 08, 2016 at 04:19:36AM -0500, Yong Bakos wrote: > On Apr 5, 2016, at 6:12 PM, Bryce Harrington <br...@osg.samsung.com> wrote: > > > > On Sat, Apr 02, 2016 at 04:48:12PM -0500, Yong Bakos wrote: > >> From: Yong Bakos <yba...@humanoriented.com> > >> > >> 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 <yba...@humanoriented.com> > > > > Thanks for chasing down the idiosyncrasies. > > > > Reviewed-by: Bryce Harrington <br...@osg.samsung.com> > > > > Bryce > > Just following up to see if anyone else has feedback or is willing > to merge this. Thanks for reviewing!
I'm definitely fine to merge it. Protocol changes are pretty fundamental to the project so I try not to merge even straightforward fixes too hastily, in case others have concerns or spot issues I didn't. I usually make a pass through the patch tracker once a week (usually Monday-ish) to clear out everything trivial and non-controversial, or items that have accumulated adequate R-b's. I intend to land this one on my next pass if someone else doesn't. Bryce > yong > > > >> --- > >> protocol/wayland.xml | 128 > >> ++++++++++++++++++++++++++------------------------- > >> 1 file changed, 65 insertions(+), 63 deletions(-) > >> > >> diff --git a/protocol/wayland.xml b/protocol/wayland.xml > >> index 8739cd3..8ebf6bf 100644 > >> --- a/protocol/wayland.xml > >> +++ b/protocol/wayland.xml > >> @@ -70,9 +70,9 @@ > >> own set of error codes. The message is an 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 receive 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 @@ > >> local 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="x coordinate in > >> surface-relative coordinates"/> > >> + <arg name="y" type="fixed" summary="y coordinate in > >> surface-relative coordinates"/> > >> + <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="x coordinate in > >> surface-relative coordinates"/> > >> + <arg name="y" type="fixed" summary="y coordinate in > >> surface-relative coordinates"/> > >> </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 --> > >> @@ -1231,7 +1233,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"> > >> @@ -1255,9 +1257,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"> > >> @@ -1533,7 +1535,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"> > >> @@ -1542,7 +1544,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 --> > >> @@ -1701,7 +1703,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"> > >> @@ -1751,7 +1753,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 --> > >> @@ -1832,8 +1834,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="x coordinate in > >> surface-relative coordinates"/> > >> <arg name="surface_y" type="fixed" summary="y coordinate in > >> surface-relative coordinates"/> > >> </event> > >> @@ -1846,8 +1848,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"> > >> @@ -1881,10 +1883,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"> > >> @@ -1916,8 +1918,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-relative coordinate space"/> > >> </event> > >> > >> <!-- Version 3 additions --> > >> @@ -2020,7 +2022,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"> > >> @@ -2073,8 +2075,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> > >> > >> @@ -2100,9 +2102,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"> > >> @@ -2110,8 +2112,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> > >> > >> @@ -2123,8 +2125,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"> > >> @@ -2142,10 +2144,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"> > >> @@ -2154,11 +2156,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 --> > >> @@ -2211,9 +2213,9 @@ > >> this ID. The ID ceases to be valid after a touch up event and may be > >> re-used 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="x coordinate in surface-relative > >> coordinates"/> > >> <arg name="y" type="fixed" summary="y coordinate in surface-relative > >> coordinates"/> > >> @@ -2225,7 +2227,7 @@ > >> this touchpoint and the touch point's ID is released and may be > >> re-used 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> > >> -- > >> 2.7.2 > >> > >> _______________________________________________ > >> wayland-devel mailing list > >> wayland-devel@lists.freedesktop.org > >> https://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel