[PATCH] protocol: Add summaries to event parameters

[Pekka Paalanen]

On Thu, 31 Mar 2016 08:36:56 -0500
Yong Bakos <junk at humanoriented.com> wrote:

> > On Mar 30, 2016, at 12:53 PM, Bryce Harrington <bryce at osg.samsung.com> wrote:
> > 
> > On Tue, Mar 29, 2016 at 06:04:49PM -0500, Yong Bakos wrote:  
> >> From: Yong Bakos <ybakos at 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 <ybakos at humanoriented.com>  
> > 
> > Will be nice to see fewer warnings!  :-)
> > 
> > My review is a cursory doublecheck of each line against the
> > corresponding description field in wayland.xml.  Everything looks fine,
> > but I have a few suggestions/comments below.
> >   
> >> ---
> >> protocol/wayland.xml | 128 ++++++++++++++++++++++++++-------------------------
> >> 1 file changed, 65 insertions(+), 63 deletions(-)

> >> -      <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 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"/>  
> > 
> > I don't know if it really matters, but the description uses the phrasing
> > "surface local coordinates" so I wonder if the x and y coordinate
> > summaries should follow suit?  
> 
> /Yes/! But in this patch I forced myself to stick to precedent for all
> summary additions. I have a separate patch coming that standardizes the
> use of "surface local," along with numerous grammar/spelling corrections.

Hi,

I think I'm to blame for the "surface local coordinates" term.

In the early days, most people assumed global coordinates would exist
and that most things would use global coordinates in the protocol. That
is not the case in Wayland, so I wanted to emphasize that the
coordinates are really local and relative to the given surface, whether
the point is inside or outside the surface.

Nowadays I slightly regret having "local" in the term, it feels
redundant. "Surface coordinates" already says it all.

However, that should not be confused with "surface's coordinates" which
refers to surface's position in some other coordinate system.

Should we just stick to "surface local coordinates" or what, I'm not
sure. I think that term is pretty established by now, even if it sounds
clunky.

Or maybe no-one else thinks it's clunky?

Short and descriptive terms are hard to find.


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20160401/2ca38058/attachment.sig>