diff --git a/src/egl/wayland/wayland-drm/wayland-drm.xml b/src/egl/wayland/wayland-drm/wayland-drm.xml
index 5e64622..7cf06d9 100644
--- a/src/egl/wayland/wayland-drm/wayland-drm.xml
+++ b/src/egl/wayland/wayland-drm/wayland-drm.xml
@@ -27,19 +27,31 @@
     THIS SOFTWARE.
   </copyright>
 
-  <!-- drm support. This object is created by the server and published
-       using the display's global event. -->
   <interface name="wl_drm" version="2">
+    <description summary="drm support">
+      This object is created by the server and published using the
+      display's global event.
+    </description>
+
     <enum name="error">
-      <entry name="authenticate_fail" value="0"/>
-      <entry name="invalid_format" value="1"/>
-      <entry name="invalid_name" value="2"/>
+      <description summary="error values">
+        These errors can be emitted in response to wl_drm requests.
+      </description>
+      <entry name="authenticate_fail" value="0"
+             summary="authentication failure"/>
+      <entry name="invalid_format" value="1"
+             summary="buffer format is not supported"/>
+      <entry name="invalid_name" value="2"
+             summary="invalid name for buffer creation"/>
     </enum>
 
     <enum name="format">
-      <!-- The drm format codes match the #defines in drm_fourcc.h.
-           The formats actually supported by the compositor will be
-           reported by the format event. -->
+      <description summary="pixel formats">
+        The drm format codes match the #defines in drm_fourcc.h.
+
+        The formats actually supported by the compositor will be
+        reported by the format event.
+      </description>
       <entry name="c8" value="0x20203843"/>
       <entry name="rgb332" value="0x38424752"/>
       <entry name="bgr233" value="0x38524742"/>
@@ -100,84 +112,113 @@
       <entry name="yvu444" value="0x34325659"/>
     </enum>
 
-    <!-- Call this request with the magic received from drmGetMagic().
-         It will be passed on to the drmAuthMagic() or
-         DRIAuthConnection() call.  This authentication must be
-         completed before create_buffer could be used. -->
     <request name="authenticate">
-      <arg name="id" type="uint"/>
+      <description summary="authentication request">
+        Call this request with the magic received from drmGetMagic().
+
+        It will be passed on to the drmAuthMagic() or
+        DRIAuthConnection() call.  This authentication must be
+        completed before create_buffer could be used.
+      </description>
+      <arg name="id" type="uint" summary="drm magic identifier"/>
     </request>
 
-    <!-- Create a wayland buffer for the named DRM buffer.  The DRM
-         surface must have a name using the flink ioctl -->
     <request name="create_buffer">
-      <arg name="id" type="new_id" interface="wl_buffer"/>
-      <arg name="name" type="uint"/>
-      <arg name="width" type="int"/>
-      <arg name="height" type="int"/>
-      <arg name="stride" type="uint"/>
-      <arg name="format" type="uint"/>
+      <description summary="create drm buffer">
+        Create a wayland buffer for the named DRM buffer.
+
+        The DRM surface must have a name using the flink ioctl.
+      </description>
+      <arg name="id" type="new_id" interface="wl_buffer"
+           summary="wl_buffer assigned to this drm buffer"/>
+      <arg name="name" type="uint" summary="unique buffer name"/>
+      <arg name="width" type="int" summary="buffer width"/>
+      <arg name="height" type="int" summary="buffer height"/>
+      <arg name="stride" type="uint" summary="stride of a line"/>
+      <arg name="format" type="uint" summary="see wl_drm_format"/>
     </request>
 
-    <!-- Create a wayland buffer for the named DRM buffer.  The DRM
-         surface must have a name using the flink ioctl -->
     <request name="create_planar_buffer">
-      <arg name="id" type="new_id" interface="wl_buffer"/>
-      <arg name="name" type="uint"/>
-      <arg name="width" type="int"/>
-      <arg name="height" type="int"/>
-      <arg name="format" type="uint"/>
-      <arg name="offset0" type="int"/>
-      <arg name="stride0" type="int"/>
-      <arg name="offset1" type="int"/>
-      <arg name="stride1" type="int"/>
-      <arg name="offset2" type="int"/>
-      <arg name="stride2" type="int"/>
+      <description summary="create planar drm buffer">
+        Create a wayland buffer for the named planar DRM buffer.
+
+        The DRM surface must have a name using the flink ioctl.
+      </description>
+      <arg name="id" type="new_id" interface="wl_buffer"
+           summary="wl_buffer assigned to this drm buffer"/>
+      <arg name="name" type="uint" summary="unique buffer name"/>
+      <arg name="width" type="int" summary="buffer width"/>
+      <arg name="height" type="int" summary="buffer height"/>
+      <arg name="format" type="uint" summary="see wl_drm_format"/>
+      <arg name="offset0" type="int" summary="first plane offset"/>
+      <arg name="stride0" type="int" summary="first plane stride"/>
+      <arg name="offset1" type="int" summary="second plane offset"/>
+      <arg name="stride1" type="int" summary="second plane stride"/>
+      <arg name="offset2" type="int" summary="third plane offset"/>
+      <arg name="stride2" type="int" summary="third plane stride"/>
     </request>
 
-    <!-- Notification of the path of the drm device which is used by
-         the server.  The client should use this device for creating
-         local buffers.  Only buffers created from this device should
-         be be passed to the server using this drm object's
-         create_buffer request. -->
     <event name="device">
-      <arg name="name" type="string"/>
+      <description summary="drm device of the server">
+        Notification of the path of the drm device which is used by the
+        server.
+
+        The client should use this device for creating local buffers.
+        Only buffers created from this device should be be passed to
+        the server using this drm object's create_buffer request.
+      </description>
+      <arg name="name" type="string" summary="path of the drm device"/>
     </event>
 
     <event name="format">
-      <arg name="format" type="uint"/>
+      <description summary="pixel format description">
+        Informs the client about a valid pixel format that can be used
+        for buffers.
+      </description>
+      <arg name="format" type="uint" summary="pixel format"/>
     </event>
 
-    <!-- Raised if the authenticate request succeeded -->
-    <event name="authenticated"/>
+    <event name="authenticated">
+      <description summary="successful authentication">
+        Raised if the authenticate request succeeded.
+      </description>
+    </event>
 
     <enum name="capability" since="2">
-      <description summary="wl_drm capability bitmask">
-        Bitmask of capabilities.
+      <description summary="capability description">
+        Lists the available capabilities the server can expose.
       </description>
       <entry name="prime" value="1" summary="wl_drm prime available"/>
     </enum>
 
     <event name="capabilities">
-      <arg name="value" type="uint"/>
+      <description summary="capabilities bitmask">
+        Bitmask of capabilities supported by the server.
+      </description>
+      <arg name="value" type="uint" summary="capabilities"/>
     </event>
 
     <!-- Version 2 additions -->
 
-    <!-- Create a wayland buffer for the prime fd.  Use for regular and planar
-         buffers.  Pass 0 for offset and stride for unused planes. -->
     <request name="create_prime_buffer" since="2">
-      <arg name="id" type="new_id" interface="wl_buffer"/>
-      <arg name="name" type="fd"/>
-      <arg name="width" type="int"/>
-      <arg name="height" type="int"/>
-      <arg name="format" type="uint"/>
-      <arg name="offset0" type="int"/>
-      <arg name="stride0" type="int"/>
-      <arg name="offset1" type="int"/>
-      <arg name="stride1" type="int"/>
-      <arg name="offset2" type="int"/>
-      <arg name="stride2" type="int"/>
+      <description summary="create prime drm buffer">
+        Create a wayland buffer for the prime fd.
+
+        Use for regular and planar buffers.  Pass 0 for offset and
+        stride for unused planes.
+      </description>
+      <arg name="id" type="new_id" interface="wl_buffer"
+           summary="wl_buffer assigned to this drm buffer"/>
+      <arg name="name" type="fd" summary="prime fd"/>
+      <arg name="width" type="int" summary="buffer width"/>
+      <arg name="height" type="int" summary="buffer height"/>
+      <arg name="format" type="uint" summary="see wl_drm_format"/>
+      <arg name="offset0" type="int" summary="first plane offset"/>
+      <arg name="stride0" type="int" summary="first plane stride"/>
+      <arg name="offset1" type="int" summary="second plane offset"/>
+      <arg name="stride1" type="int" summary="second plane stride"/>
+      <arg name="offset2" type="int" summary="third plane offset"/>
+      <arg name="stride2" type="int" summary="third plane stride"/>
     </request>
 
   </interface>
