xdg-shell: Some minor clarifications

Mention set_window_geometry in configure documentation.

Add a strategic "For instance" to clarify what is just an example.

Clarify that the arguments of set_window_geometry are in the surface
local coordinate space.

Point out that the client needs to destroy a dismissed popup.

Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>

protocol/xdg-shell.xml

@@ -315,7 +315,7 @@
 
 	The width and height arguments specify a hint to the window
 	about how its surface should be resized in window geometry
-	coordinates.
+	coordinates. See set_window_geometry.
 
 	The states listed in the event specify how the width/height
 	arguments should be interpreted, and possibly how it should be
@@ -344,9 +344,9 @@
         must make a ack_configure request before the commit request,
         passing along the serial of the configure event.
 
-        The compositor might use this information to move a surface
+        For instance, the compositor might use this information to move
-        to the top left only when the client has drawn itself for
+        a surface to the top left only when the client has drawn itself
-        the maximized or fullscreen state.
+        for the maximized or fullscreen state.
 
         If the client receives multiple configure events before it
         can respond to one, it only has to ack the last configure event.
@@ -377,6 +377,9 @@
         must respect the sizing negotiations specified by the states in
         the configure event.
 
+        The arguments are given in the surface local coordinate space of
+        the wl_surface associated with this xdg_surface.
+
         The width and height must be greater than zero.
       </description>
       <arg name="x" type="int"/>
@@ -491,8 +494,9 @@
 
     <event name="popup_done">
       <description summary="popup interaction is done">
-	The popup_done event is sent out when a popup is dismissed
+	The popup_done event is sent out when a popup is dismissed by the
-	by the compositor.
+	compositor. The client should destroy the xdg_popup object at this
+	point.
       </description>
     </event>