[PATCH wayland] protocol: Clarify the meaning of NULL buffer attachment

[Derek Foreman]

This documents what has apparently been the case for ages - attaching a NULL
buffer does *not* always remove the surface content, rather it has behaviour
determined by the surface role (which may be documented elsewhere).

Signed-off-by: Derek Foreman <derekf at osg.samsung.com>
---
 protocol/wayland.xml | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 29b63be..d7f7690 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1359,8 +1359,17 @@
 	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.
+	If wl_surface.attach is sent with a NULL wl_buffer, the result is
+	determined by the surface role. For the result of attaching a NULL
+	wl_buffer to a surface with a cursor role, see the documentation for
+	wl_pointer.set_cursor.
+
+	The result of attaching a NULL buffer to a shell surface should be
+	defined by the shell protocol specification.  As the result may be
+	a posted error and a client disconnect, developers should be careful
+	to read the appropriate protocol specification.  Attaching a NULL
+	buffer to a wl_shell surface removes the surface content, but this
+	behavior is not specified for all shell protocols.
       </description>
       <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
 	   summary="buffer of surface contents"/>
-- 
2.11.0