[PATCH wayland v2] protocol: Clarify the behaviour of wl_surface.attach

[Derek Foreman]

Attaching a NULL wl_buffer to a surface is not always valid, but
the previous text indicated it was.

Instead, let's define what NULL attachment does for all the surface
roles defined in wayland.xml, stop giving a blanket definition of
its behavior in wl_surface.attach, and warn developers that they
should refer to other protocol documentation for a full understanding
of wl_surface.attach.

Signed-off-by: Derek Foreman <derekf at osg.samsung.com>
---

Changes from v1:
 pretty much everything - define NULL attach for wl_shell specifically
 and remove the generic statement from wl_surface.attach
 refer readers to "other documentation"

 protocol/wayland.xml | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 29b63be..1a76e60 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1002,6 +1002,10 @@
       the related wl_surface is destroyed. On the client side,
       wl_shell_surface_destroy() must be called before destroying
       the wl_surface object.
+
+      Attaching a NULL wl_buffer to a surface assigned a role by
+      wl_shell will remove the content from the surface after the
+      next commit.
     </description>
 
     <request name="pong">
@@ -1324,6 +1328,9 @@
       <description summary="set the surface contents">
 	Set a buffer as the content of this surface.
 
+	The role of the surface influences the behaviour of attach,
+	so this documentation is incomplete without further reading.
+
 	The new size of the surface is calculated based on the buffer
 	size transformed by the inverse buffer_transform and the
 	inverse buffer_scale. This means that the supplied buffer
@@ -1358,9 +1365,6 @@
 	the surface contents. However, if the client destroys the
 	wl_buffer before receiving the wl_buffer.release event, the surface
 	contents become undefined immediately.
-
-	If wl_surface.attach is sent with a NULL wl_buffer, the
-	following wl_surface.commit will remove the surface content.
       </description>
       <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
 	   summary="buffer of surface contents"/>
-- 
2.11.0