protocol: added basic documentation of requests and events

Signed-off-by: Timo Lotterbach <timo.lotterbach@bmw-carit.de>

2 files changed, 335 insertions, 109 deletions

diff --git a/protocol/ivi-application.xml b/protocol/ivi-application.xml
index 959b341..9201eaf 100755
--- a/protocol/ivi-application.xml
+++ b/protocol/ivi-application.xml
@@ -25,36 +25,60 @@
     </copyright>
 
     <interface name="ivi_surface" version="1">
-        <description summary="Tell property change of ivi_surface to application"/>
+        <description summary="application interface to surface in ivi compositor"/>
 
         <request name="destroy" type="destructor">
             <description summary="destroy ivi_surface"/>
         </request>
 
         <event name="visibility">
-            <description summary="visibility of ivi_surface has changed"/>
+            <description summary="visibility of surface in ivi compositor has changed">
+                The new visibility state is provided in argument visibility.
+                If visibility is 0, the surface has become invisible.
+                If visibility is not 0, the surface has become visible.
+            </description>
             <arg name="visibility" type="int"/>
         </event>
+
     </interface>
 
     <interface name="ivi_application" version="1">
-        <description summary="creation of ivi_surface"/>
+        <description summary="interface for ivi applications to use ivi compositor features"/>
 
         <request name="surface_create">
-            <description summary="ilm_surfaceCreate"/>
+            <description summary="create surface in ivi compositor">
+                surface_create will create a new surface with surface_id in ivi compositor,
+                if it does not yet exists. If the surface with surface_id already exists in
+                ivi compositor, the application content provided in argument surface will
+                be used as surface content. If an other ivi application already registered
+                content for surface with surface_id, an error event will indicate the problem.
+            </desription>
             <arg name="id_surface" type="uint"/>
             <arg name="surface" type="object" interface="wl_surface"/>
             <arg name="id" type="new_id" interface="ivi_surface"/>
         </request>
 
         <enum name="error_code">
-            <description summary="possible error codes returned in error event"/>
+            <description summary="possible error codes returned by ivi compositor">
+                These error codes define all possible error codes returned by ivi compositor
+                on server-side errors.
+            </description>
             <entry name="unknown_error"   value="1" summary="unknown error encountered"/>
             <entry name="resource_in_use" value="2" summary="resource is in use and can not be shared"/>
         </enum>
 
         <event name="error">
-            <description summary="request resulted in server-side error"/>
+            <description summary="server-side error detected">
+                The ivi compositor encountered error while processing a request by this
+                application. The error is defined by argument error_code and optional
+                error_text.
+                If the application requires to associate this error event to a request,
+                it can
+                    1. send request
+                    2. force display roundtrip
+                    3. check, if error event was received
+                 but this restricts the application to have only one open request at a time.
+            </description>
             <arg name="error_code" type="int"/>
             <arg name="error_text" type="string" allow-null="true"/>
         </event>
diff --git a/protocol/ivi-controller.xml b/protocol/ivi-controller.xml
index 33b7df8..c6ef8f8 100755
--- a/protocol/ivi-controller.xml
+++ b/protocol/ivi-controller.xml
@@ -25,24 +25,32 @@
     </copyright>
 
     <interface name="ivi_controller_surface" version="1">
-        <description summary="Request property change of ivi_surface to server"/>
+        <description summary="controller interface to surface in ivi compositor"/>
 
         <request name="set_visibility">
-            <description summary="Set Visibility"/>
+            <description summary="set the visibility of a surface in ivi compositor">
+                 If visibility argument is 0, the surface in the ivi compositor is set to invisible.
+                 If visibility argument is not 0, the surface in the ivi compositor is set to visible.
+            </description>
             <arg name="visibility" type="uint"/>
         </request>
 
         <request name="set_opacity">
-            <description summary="Set Opacity"/>
+            <description summary="set the opacity of a surface in ivi compositor">
+                 The valid range for opacity is 0.0 (fully transparent) to 1.0 (fully opaque).
+            </description>
             <arg name="opacity" type="fixed"/>
         </request>
 
         <request name="set_source_rectangle">
-            <description summary="Set the area of wl_surface which should be used for the rendering">
-                x:      horizontal start position of the used area
-                y:      vertical start position of the used area
-                width : width of the area
-                height: height of the area
+            <description summary="set the scanout area of a surface in ivi compositor">
+                The source rectangle defines the part of the surface content, that is used for
+                compositing the surface. It can be used, if valid content of the surface is smaller
+                than the surface. Effectively it can be used to zoom the content of the surface.
+                x:      horizontal start position of scanout area within the surface
+                y:      vertical start position of scanout area within the surface
+                width:  width of scanout area within the surface
+                height: height of scanout area within the surface
             </description>
             <arg name="x" type="int"/>
             <arg name="y" type="int"/>
@@ -51,12 +59,13 @@
         </request>
 
         <request name="set_destination_rectangle">
-            <description summary="Set the destination area of a surface within a layer for rendering">
-                Set the destination area of a wl_surface within a layer for rendering. The surface will be scaled to this rectangle for rendering.
-                x:      horizontal start position of the used area
-                y:      vertical start position of the used area
-                width : width of the area
-                height: height of the area
+            <description summary="Set the destination area of a surface within a layer">
+                The destination rectangle defines the position and size of a surface on a layer.
+                The surface will be scaled to this rectangle for rendering.
+                x:      horizontal start position of surface within the layer
+                y:      vertical start position of surface within the layer
+                width : width of surface within the layer
+                height: height of surface within the layer
             </description>
             <arg name="x" type="int"/>
             <arg name="y" type="int"/>
@@ -65,33 +74,55 @@
         </request>
 
         <request name="set_configuration">
-            <description summary="request new buffer size for application content"/>
+            <description summary="request new buffer size for application content">
+                Request the client providing content for this surface, to resize of the buffers
+                provided as surface content.
+            </description>
             <arg name="width" type="int"/>
             <arg name="height" type="int"/>
         </request>
 
         <request name="set_orientation">
-            <description summary="Set Orientation"/>
+            <description summary="set the orientation of a surface in ivi compositor">
+                The orientation of a surface in ivi compositor can be rotated in 90 degree steps,
+                as defined in orientation enum.
+            </description>
             <arg name="orientation" type="int"/>
         </request>
 
         <request name="screenshot">
-            <description summary="Take screenshot"/>
+            <description summary="take screenshot of surface">
+                Store a screenshot of the surface content in the file provided by argument filename.
+            </description>
             <arg name="filename" type="string"/>
         </request>
 
         <event name="visibility">
-            <description summary="sent in response to set_visibility"/>
+            <description summary="the visibility of the surface in ivi compositor has changed">
+                The new visibility state is provided in argument visibility.
+                If visibility is 0, the surface has become invisible.
+                If visibility is not 0, the surface has become visible.
+            </description>
             <arg name="visibility" type="int"/>
         </event>
 
         <event name="opacity">
-            <description summary="sent in response to set_opacity"/>
+            <description summary="the opacity of surface in ivi compositor has changed">
+                The new opacity state is provided in argument opacity.
+                The valid range for opactiy is 0.0 (fully transparent) to 1.0 (fully opaque).
+            </description>
             <arg name="opacity" type="fixed"/>
         </event>
 
         <event name="source_rectangle">
-            <description summary="sent in response to set_source_rectangle"/>
+            <description summary="the source rectangle of surface in ivi compositor has changed">
+                The scanout region of the surface content has changed.
+                The new values for source rectangle are provided by
+                x:      new horizontal start position of scanout area within the surface
+                y:      new vertical start position of scanout area within the surface
+                width:  new width of scanout area within the surface
+                height: new height of scanout area within the surface
+            </description>
             <arg name="x" type="int"/>
             <arg name="y" type="int"/>
             <arg name="width" type="int"/>
@@ -99,7 +130,13 @@
         </event>
 
         <event name="destination_rectangle">
-            <description summary="sent in response to set_destination_rectangle"/>
+            <description summary="the destination rectangle of surface in ivi compositor has changed">
+                The new values for source rectangle are provided by
+                x:      new horizontal start position of surface within the layer
+                y:      new vertical start position of surface within the layer
+                width : new width of surface within the layer
+                height: new height of surface within the layer
+            </description>
             <arg name="x" type="int"/>
             <arg name="y" type="int"/>
             <arg name="width" type="int"/>
@@ -107,62 +144,79 @@
         </event>
 
         <event name="configuration">
-            <description summary="sent in response to set_configuration"/>
+            <description summary="the configuration of surface in ivi compositor has changed">
+                The client providing content for this surface was requested to resize the buffer
+                provided as surface content. The requested buffer size is provided by arguments
+                width and height.
+            </description>
             <arg name="width" type="int"/>
             <arg name="height" type="int"/>
         </event>
 
         <enum name="orientation">
-            <description summary="orientation presets in degrees"/>
-            <entry name="0_degrees" value="0"
-             summary="not rotated"/>
-            <entry name="90_degrees" value="1"
-             summary="rotated 90 degrees clockwise"/>
-            <entry name="180_degrees" value="2"
-             summary="rotated 180 degrees clockwise"/>
-            <entry name="270_degrees" value="3"
-             summary="rotated 270 degrees clockwise"/>
+            <description summary="orientation presets in degrees">
+                The surfaces in ivi controller can be rotated in 90 degrees steps.
+                This enum defines all valid orientations for surfaces.
+            </description>
+            <entry name="0_degrees"   value="0" summary="not rotated"/>
+            <entry name="90_degrees"  value="1" summary="rotated 90 degrees clockwise"/>
+            <entry name="180_degrees" value="2" summary="rotated 180 degrees clockwise"/>
+            <entry name="270_degrees" value="3" summary="rotated 270 degrees clockwise"/>
         </enum>
 
         <event name="orientation">
-            <description summary="sent in response to set_orientation"/>
+            <description summary="the orientation of surface in ivi compositor has changed">
+                The new orientation status is provided by argument orientation.
+            </description>
             <arg name="orientation" type="int"/>
         </event>
 
         <enum name="pixelformat">
-            <description summary="pixel format values"/>
-            <entry name="r_8" value="0"
-             summary="8 bit luminance surface"/>
-            <entry name="rgb_888" value="1"
-             summary="24 bit rgb surface"/>
-            <entry name="rgba_8888" value="2"
-             summary="24 bit rgb surface with 8 bit alpha"/>
-            <entry name="rgb_565" value="3"
-             summary="16 bit rgb surface"/>
-            <entry name="rgba_5551" value="4"
-             summary="16 bit rgb surface with binary mask"/>
-            <entry name="rgba_6661" value="5"
-             summary="18 bit rgb surface with binary mask"/>
-            <entry name="rgba_4444" value="6"
-             summary="12 bit rgb surface with 4 bit alpha"/>
-            <entry name="unknown" value="7"
-             summary="unknown"/>
+            <description summary="pixel format values">
+                Applications can provide buffers as surface content with differernt buffer
+                properties. This enum defines all supported buffer configurations.
+            </description>
+            <entry name="r_8"       value="0" summary="8 bit luminance surface"/>
+            <entry name="rgb_888"   value="1" summary="24 bit rgb surface"/>
+            <entry name="rgba_8888" value="2" summary="24 bit rgb surface with 8 bit alpha"/>
+            <entry name="rgb_565"   value="3" summary="16 bit rgb surface"/>
+            <entry name="rgba_5551" value="4" summary="16 bit rgb surface with binary mask"/>
+            <entry name="rgba_6661" value="5" summary="18 bit rgb surface with binary mask"/>
+            <entry name="rgba_4444" value="6" summary="12 bit rgb surface with 4 bit alpha"/>
+            <entry name="unknown"   value="7" summary="unknown"/>
         </enum>
 
         <event name="pixelformat">
-            <description summary="pixelformat"/>
+            <description summary="pixelformat for surface in ivi compositor has changed">
+                When client attach buffers as surface content, these buffers have a pixelformat
+                configuration. If the pixelformat of a newly attached buffer is different from
+                the previous buffer configuration, this event is raised.
+                This is also done, when the first buffer is provided by application.
+            </description>
             <arg name="pixelformat" type="int"/>
         </event>
 
         <event name="layer">
-            <description summary="Receive a ivi_layer this ivi_surface belongs"/>
+            <description summary="surface in ivi compositor was added to a layer">
+                This surface was added to the render order of the layer defined by argument layer.
+                This is essential for a surface to become visible on screen, since ivi compositors
+                will only render layers (or more precise all surfaces in the render order of a layer).
+            </description>
             <arg name="layer" type="object" interface="ivi_controller_layer" allow-null="true"/>
         </event>
 
-        <request name="send_stats"/>
+        <request name="send_stats">
+            <description summary="request statistics for surface in ivi compositor"/>
+                These stats contain information required for monitoring, debugging, logging
+                and tracing.
+            </description>
+        </request>
 
         <event name="stats">
-            <description summary="sent in response to send_stats"/>
+            <description summary="receive updated statistics for surface in ivi compositor">
+                The information contained in this event is essential for monitoring, debugging,
+                logging and tracing support in IVI systems.
+            </description>
             <arg name="redraw_count" type="uint"/>
             <arg name="frame_count" type="uint"/>
             <arg name="update_count" type="uint"/>
@@ -171,16 +225,24 @@
         </event>
 
         <request name="destroy" type="destructor">
-            <description summary="destroy ivi_controller_surface"/>
+            <description summary="destroy ivi_controller_surface">
+                Request to destroy the ivi_controller_surface. If argument
+                destroy_scene_object id not 0, the surface will be destroyed in
+                ivi compositor. If argument is 0, only the proxy object is destroyed.
+            </description>
             <arg name="destroy_scene_object" type="int"/>
         </request>
 
         <event name="destroyed">
-            <description summary="destroyed surface event"/>
+            <description summary="ivi_controller_surface was destroyed"/>
         </event>
 
         <enum name="content_state">
-            <description summary="all possible states of content for a surface"/>
+            <description summary="all possible states of content for a surface">
+                This enum defines all possible content states of a surface. This is
+                required, since surfaces in ivi compositor can exist without applications
+                providing content for them.
+            </description>
             <entry name="content_available" value="1"
                    summary="application provided wl_surface for this surface"/>
             <entry name="content_removed" value="2"
@@ -188,41 +250,67 @@
         </enum>
 
         <event name="content">
-            <description summary="content state for surface has changed"/>
+            <description summary="content state for surface has changed">
+                Surfaces in ivi compositor can exist without any application or controller
+                referencing it. All surfaces initially have no content. This event indicates
+                when content state has changed. All possible content states are defined
+                in enum content_state.
+            </description>
             <arg name="content_state" type="int"/>
         </event>
 
         <request name="set_input_focus">
-            <description summary="set input_focus to this surface to direct non-graphical inputs (e.g. keyboard) to application providing this surface"/>
+            <description summary="set input focus to this surface">
+                Set input focus state of surface in ivi compositor. If the surface has input
+                focus, all non-graphical inputs (e.g. keyboard) are directed to the application
+                providing the content for this surface.
+                Only one surface can have input focus at a time, so if input focus is enabled
+                for one surface, any other surface with input focus will loose focus.
+                If argument enabled is 0, the input focus from this surface is removed, no
+                surface will have input focus.
+                If argument enabled is not 0, input focus for this surface is enabled.
+            </description>
             <arg name="enabled" type="int"/>
         </request>
 
         <event name="input_focus">
-            <description summary="received if input focus of surface has changed"/>
+            <description summary="input focus of surface in ivi compositor has changed">
+                The new input focus state is provided in argument enabled: If enabled is 0,
+                this surface has no longer the input focus. If enbaled is not 0, this surface
+                now has input focus enabled.
+            </description>
             <arg name="enabled" type="int"/>
         </event>
 
     </interface>
 
     <interface name="ivi_controller_layer" version="1">
-        <description summary="Request property change of ivi_layer and add/remove ivi_surface from ivi_layer to server"/>
+        <description summary="controller interface to layer in ivi compositor">
 
         <request name="set_visibility">
-            <description summary="Set Visibility"/>
+            <description summary="set visibility of layer in ivi compositor">
+                If visibility argument is 0, the layer in the ivi compositor is set to invisible.
+                If visibility argument is not 0, the layer in the ivi compositor is set to visible.
+            </description>
             <arg name="visibility" type="uint"/>
         </request>
 
         <request name="set_opacity">
-            <description summary="Set Opacity"/>
+            <description summary="set opacity of layer in ivi compositor">
+                The valid range for opacity is 0.0 (fully transparent) to 1.0 (fully opaque).
+            </description>
             <arg name="opacity" type="fixed"/>
         </request>
 
         <request name="set_source_rectangle">
-            <description summary="Set the area of layer which should be used for the rendering">
-                x:      horizontal start position of the used area
-                y:      vertical start position of the used area
-                width : width of the area
-                height: height of the area
+            <description summary="set the scanout area of a layer in ivi compositor">
+                The source rectangle defines the part of the layer content, that is used for
+                compositing the screen. It can be used, if valid content of the layer is smaller
+                than the layer. Effectively it can be used to zoom the content of the layer.
+                x:      horizontal start position of scanout area within the layer
+                y:      vertical start position of scanout area within the layer
+                width:  width of scanout area within the layer
+                height: height of scanout area within the layer
             </description>
             <arg name="x" type="int"/>
             <arg name="y" type="int"/>
@@ -231,12 +319,13 @@
         </request>
 
         <request name="set_destination_rectangle">
-            <description summary="Set the destination area on the display for a layer">
-                Set the destination area on the display for a layer. The layer will be scaled and positioned to this rectangle for rendering
-                x:      horizontal start position of the used area
-                y:      vertical start position of the used area
-                width : width of the area
-                height: height of the area
+           <description summary="Set the destination area of a layer within a screen">
+                The destination rectangle defines the position and size of a layer on a screen.
+                The layer will be scaled to this rectangle for rendering.
+                x:      horizontal start position of layer within the screen
+                y:      vertical start position of layer within the screen
+                width : width of surface within the screen
+                height: height of surface within the screen
             </description>
             <arg name="x" type="int"/>
             <arg name="y" type="int"/>
@@ -245,52 +334,92 @@
         </request>
 
         <request name="set_configuration">
-            <description summary="Set new configuration for layer"/>
+            <description summary="request new size for layer">
+                Layers are created with an initial size, but they can be resized at runtime.
+                This request changes the widht and height of a layer.
+            </description>
             <arg name="width" type="int"/>
             <arg name="height" type="int"/>
         </request>
 
         <request name="set_orientation">
-            <description summary="Set Orientation"/>
+            <description summary="set the orientation of a layer in ivi compositor">
+                The orientation of a layer in ivi compositor can be rotated in 90 degree steps,
+                as defined in orientation enum.
+            </description>
             <arg name="orientation" type="int"/>
         </request>
 
         <request name="screenshot">
-            <description summary="Take screenshot"/>
+            <description summary="take screenshot of layer">
+                Store a screenshot of the layer content in the file provided by argument filename.
+            </description>
             <arg name="filename" type="string"/>
         </request>
 
         <request name="clear_surfaces">
-            <description summary="remove all ivi_surfaces from a layer"/>
+            <description summary="remove all surfaces from layer render order">
+                A layer has no content assigned to itself, it is a container for surfaces.
+                This request removes all surfaces from the layer render order.
+                Note: the surfaces are not destroyed, they are just no longer contained by
+                the layer.
+            </description>
         </request>
 
         <request name="add_surface">
-            <description summary="add a ivi_surface to top order of a ivi_layer"/>
+            <description summary="add a surface to layer render order at nearest z-position">
+                A layer has no content assigned to itself, it is a container for surfaces.
+                This request adds a surface to the topmost position of the layer render order.
+                The added surface will cover all other surfaces of the layer.
+            </description>
             <arg name="surface" type="object" interface="ivi_controller_surface"/>
         </request>
 
         <request name="remove_surface">
-            <description summary="remove a ivi_surface from a layer"/>
+            <description summary="remove a surface from layer render order">
+                A layer has no content assigned to itself, it is a container for surfaces.
+                This request removes one surfaces from the layer render order.
+                Note: the surface is not destroyed, it is just no longer contained by
+                the layer.
+            </description>
             <arg name="surface" type="object" interface="ivi_controller_surface"/>
         </request>
 
         <request name="set_render_order">
-            <description summary="Set Render Order"/>
+            <description summary="set render order of layer">
+                A layer has no content assigned to itself, it is a container for surfaces.
+                This request removes all surfaces from the layer render order and set a
+                completely new render order.
+            </description>
             <arg name="id_surfaces" type="array"/>
         </request>
 
         <event name="visibility">
-            <description summary="sent in response to set_visibility"/>
+            <description summary="the visibility of the layer in ivi compositor has changed">
+                The new visibility state is provided in argument visibility.
+                If visibility is 0, the layer has become invisible.
+                If visibility is not 0, the layer has become visible.
+            </description>
             <arg name="visibility" type="int"/>
         </event>
 
         <event name="opacity">
-            <description summary="sent in response to set_opacity"/>
+            <description summary="the opacity of layer in ivi compositor has changed">
+                The new opacity state is provided in argument opacity.
+                The valid range for opactiy is 0.0 (fully transparent) to 1.0 (fully opaque).
+            </description>
             <arg name="opacity" type="fixed"/>
         </event>
 
         <event name="source_rectangle">
-            <description summary="sent in response to set_source_rectangle"/>
+            <description summary="the source rectangle of layer in ivi compositor has changed">
+                The scanout region of the layer content has changed.
+                The new values for source rectangle are provided by
+                x:      new horizontal start position of scanout area within the layer
+                y:      new vertical start position of scanout area within the layer
+                width:  new width of scanout area within the layer
+                height: new height of scanout area within the layer
+            </description>
             <arg name="x" type="int"/>
             <arg name="y" type="int"/>
             <arg name="width" type="int"/>
@@ -298,7 +427,13 @@
         </event>
 
         <event name="destination_rectangle">
-            <description summary="sent in response to set_destination_rectangle"/>
+            <description summary="the destination rectangle of layer in ivi compositor has changed">
+                The new values for source rectangle are provided by
+                x:      new horizontal start position of layer within the screen
+                y:      new vertical start position of layer within the screen
+                width : new width of layer within the screen
+                height: new height of layer within the screen
+            </description>
             <arg name="x" type="int"/>
             <arg name="y" type="int"/>
             <arg name="width" type="int"/>
@@ -306,23 +441,36 @@
         </event>
 
         <event name="configuration">
-            <description summary="sent in response to set_configuration"/>
+            <description summary="the configuration of layer in ivi compositor has changed">
+                The layer was resized. The new layer size is provided by arguments
+                width and height.
+            </description>
             <arg name="width" type="int"/>
             <arg name="height" type="int"/>
         </event>
 
         <event name="orientation">
-            <description summary="sent in response to set_orientation"/>
+            <description summary="the orientation of layer in ivi compositor has changed">
+                The new orientation status is provided by argument orientation.
+            </description>
             <arg name="orientation" type="int"/>
         </event>
 
         <event name="screen">
-            <description summary="Receive a wl_output this ivi_layer belongs"/>
+            <description summary="layer in ivi compositor was added to a screen">
+                This layer was added to the render order of the screen defined by argument screen.
+                This is essential for a layer to become visible on screen, since ivi compositors
+                will only render screens (or more precise all layers in the render order of a screen).
+            </description>
             <arg name="screen" type="object" interface="wl_output" allow-null="true"/>
         </event>
 
         <request name="destroy" type="destructor">
-            <description summary="destroy ivi_controller_layer"/>
+            <description summary="destroy ivi_controller_layer">
+                Request to destroy the ivi_controller_layer. If argument
+                destroy_scene_object id not 0, the layer will be destroyed in
+                ivi compositor. If argument is 0, only the proxy object is destroyed.
+            </description>
             <arg name="destroy_scene_object" type="int"/>
         </request>
 
@@ -333,48 +481,78 @@
     </interface>
 
     <interface name="ivi_controller_screen" version="1">
-        <description summary="Request add/remove layer from ivi_layer to server"/>
+        <description summary="controller interface to screen in ivi compositor"/>
 
         <request name="destroy" type="destructor">
             <description summary="destroy ivi_controller_screen"/>
         </request>
 
         <request name="clear">
-            <description summary="remove all ivi_layers from wl_output"/>
+            <description summary="remove all layers from screen render order">
+                A screen has no content assigned to itself, it is a container for layers.
+                This request removes all layers from the screen render order.
+                Note: the layers are not destroyed, they are just no longer contained by
+                the screen.
+            </description>
         </request>
 
         <request name="add_layer">
-            <description summary="add a ivi_layer to top order of a wl_output"/>
+            <description summary="add a layer to screen render order at nearest z-position">
+                A screen has no content assigned to itself, it is a container for layers.
+                This request adds a layers to the topmost position of the screen render order.
+                The added layer will cover all other layers of the screen.
+            </description>
             <arg name="layer" type="object" interface="ivi_controller_layer"/>
         </request>
 
         <request name="screenshot">
-            <description summary="Take screenshot"/>
+            <description summary="take screenshot of screen">
+                Store a screenshot of the screen content in the file provided by argument filename.
+            </description>
             <arg name="filename" type="string"/>
         </request>
 
         <request name="set_render_order">
-            <description summary="Set Render Order"/>
+            <description summary="set render order of screen">
+                A screen has no content assigned to itself, it is a container for layers.
+                This request removes all layers from the screen render order and set a
+                completely new render order.
+            </description>
             <arg name="id_layers" type="array"/>
         </request>
 
     </interface>
 
     <interface name="ivi_controller" version="1">
-        <description summary="Interface for central controller of layers and surfaces"/>
+        <description summary="interface for ivi controllers to use ivi compositor features"/>
 
         <request name="commit_changes">
-            <description summary="commit changes and request done by client"/>
+            <description summary="commit all changes requested by client">
+                All requests are not applied directly to scene object, so a controller
+                can set different properties and apply the changes all at once.
+                Note: there's an exception to this. Creation and destruction of
+                scene objects is executed immediately.
+            </description>
         </request>
 
         <event name="screen">
-            <description summary="Receive new additional screen controller"/>
+            <description summary="new screen is available">
+                A new screen is announced to the controller. This is typically
+                the case in two cases:
+                    1. controller was just started, ivi compositor announces existing screen
+                    2. a new screen was added to the system at runtime
+            </description>
             <arg name="id_screen" type="uint"/>
             <arg name="screen" type="new_id" interface="ivi_controller_screen"/>
         </event>
 
         <request name="layer_create">
-            <description summary="ilm_layerCreateWithDimension"/>
+            <description summary="create layer in ivi compositor">
+                layer_create will create a new layer with id_layer in ivi compositor,
+                if it does not yet exists. If the layer with id_layer already exists in
+                ivi compositor, a handle to the existing layer is returned and width and
+                height properties are ignored.
+            </desription>
             <arg name="id_layer" type="uint"/>
             <arg name="width" type="int"/>
             <arg name="height" type="int"/>
@@ -382,36 +560,60 @@
         </request>
 
         <event name="layer">
-            <description summary="Receive id_layer and a layer controller"/>
+            <description summary="new layer is available">
+                A new layer is announced to the controller.
+            </description>
             <arg name="id_layer" type="uint"/>
         </event>
 
         <request name="surface_create">
-            <description summary="create surface controller"/>
+            <description summary="create surface in ivi compositor">
+                surface_create will create a new surface with id_surface in ivi compositor,
+                if it does not yet exists. If the surface with id_surface already exists in
+                ivi compositor, a handle to the existing surface is returned.
+            </desription>
             <arg name="id_surface" type="uint"/>
             <arg name="id" type="new_id" interface="ivi_controller_surface"/>
         </request>
 
         <event name="surface">
-            <description summary="Receive id_surface and a controller to control ivi_surface"/>
+            <description summary="new surface is available">
+                A new surface is announced to the controller.
+            </description>
             <arg name="id_surface" type="uint"/>
         </event>
 
         <enum name="object_type">
-            <description summary="available object types in ivi compositor scene"/>
+            <description summary="available object types in ivi compositor scene">
+                This enum defines all scene object available in ivi compositor.
+            </description>
             <entry name="surface" value="1" summary="surface object type"/>
             <entry name="layer"   value="2" summary="layer object type"/>
             <entry name="screen"  value="3" summary="screen object type"/>
         </enum>
 
         <enum name="error_code">
-            <description summary="possible error codes returned in error event"/>
+            <description summary="possible error codes returned in error event">
+                These error codes define all possible error codes returned by ivi compositor
+                on server-side errors.
+            </description>
             <entry name="unknown_error" value="1" summary="unknown error encountered"/>
             <entry name="file_error"    value="2" summary="file i/o error encountered"/>
         </enum>
 
         <event name="error">
-            <description summary="request resulted in server-side error"/>
+            <description summary="server-side error detected">
+                The ivi compositor encountered error while processing a request by this
+                controller. The error is defined by argument error_code and optional
+                error_text. Additionally the object type and id is contained in the error
+                event to provide some detailes to handle the error.
+                If the controller requires to associate this error event to a request,
+                it can
+                    1. send request
+                    2. force display roundtrip
+                    3. check, if error event was received
+                 but this restricts the controller to have only one open request at a time.
+            </description>
             <arg name="object_id" type="int"/>
             <arg name="object_type" type="int"/>
             <arg name="error_code" type="int"/>