From: SooChan Lim <sc1.lim@samsung.com>
Date: Fri, 23 Dec 2022 07:33:14 +0000 (+0900)
Subject: tizen_policy: specify the descrption of the tizen_policy interface
X-Git-Tag: submit/tizen/20230209.084950~2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=dad9baf7f56686541dc4d5ac18737e43d7d1ca53;p=platform%2Fcore%2Fuifw%2Fwayland-extension.git

tizen_policy: specify the descrption of the tizen_policy interface

Change-Id: Ifc13a0a7e8a2931a60cf6e9cd1a389d510c05557
---

diff --git a/protocol/tizen/tizen-extension.xml b/protocol/tizen/tizen-extension.xml
index 4b0680d..5db511e 100644
--- a/protocol/tizen/tizen-extension.xml
+++ b/protocol/tizen/tizen-extension.xml
@@ -10,7 +10,7 @@
         Create a tizen_resource interface for the given surface.
       </description>
       <arg name="id" type="new_id" interface="tizen_resource" summary="the new tizen_resource object"/>
-      <arg name="surface" type="object" interface="wl_surface" summary="the the surface object"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="destroy" type="destructor">
@@ -45,293 +45,538 @@
   </interface>
 
   <interface name="tizen_policy" version="12">
+    <description summary="tizen-specific policy for window management">
+      The tizen_policy provides tizen-specific requests and events for window
+      management at Tizen Platform.
+
+      [TODO] Explain the window layer at the display server. Need to explain the
+      window layer to understand the requests and the events at tizen_policy
+      interface.
+    </description>
+
     <request name="get_visibility">
-      <arg name="id" type="new_id" interface="tizen_visibility" summary="new visibility object"/>
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="get a visibility object">
+        Create a visibility interface for the given surface.
+      </description>
+      <arg name="id" type="new_id" interface="tizen_visibility" summary="the new visibility object"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="get_position">
-      <arg name="id" type="new_id" interface="tizen_position" summary="new position object"/>
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="get a position object">
+        Create a position interface for the given surface.
+        [TODO]: need to explain the relationship with zxdg_positioner_v6
+      </description>
+      <arg name="id" type="new_id" interface="tizen_position" summary="the new position object"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="activate">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="activate the surface">
+        Activate the given surface. A client requests this when a client wants
+        to raise at the top of the windows stack in the window's layer at the
+        display server and also wants to get a keyboard focus from the display
+        server. However the display server does not always set the focus on the
+        reqested surface. It depends on the focus policy of the display server.
+        A client just demands a keyboard focus via this request.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="activate_below_by_res_id">
-      <arg name="res_id" type="uint" />
-      <arg name="below_res_id" type="uint" />
+      <description summary="activate the res_id and position below res_id">
+        Activate the surface associated with the given res_id and position it
+        below the surface associated with the below_res_id. A client uses this
+        reuquest when it want to change the order of the window stack with the
+        gloal resource ids which are the surfaces belonging to different
+        processes. However, this requestit does not work when the surface
+        associated with the below_res_id is a parent of the surface assicated
+        with the res_id.
+      </description>
+      <arg name="res_id" type="uint" summary="the global resource id"/>
+      <arg name="below_res_id" type="uint" summary="the global resource id"/>
     </request>
 
     <request name="raise">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="raise the surface">
+         This request raises the given surface to the top of the window stack
+         in a window layer. A client can decide the window layer with the
+         window_type for the given surface through the set_type request of
+         tizen_policy interface. The surface positions at the top in the window
+         layer.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="lower">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="lower the surface">
+        This request lowers the given surface to the bottom of the window stack
+        in a window layer. The surface positions at the bottom in the window
+        layer.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="lower_by_res_id">
-      <arg name="res_id" type="uint" />
+      <description summary="lower the res_id">
+        This request lowers the surface associated with the given res_id to the
+        bottom of the window stack in a window layer. The surface positions at
+        the bottom in the window layer.
+      </description>
+      <arg name="res_id" type="uint" summary="the global resource id"/>
     </request>
 
     <request name="set_focus_skip">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="be unable to be the focused surface">
+        This request makes the given surface unable to be the focused surface.
+        The display server must not give the focus to the surface.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="unset_focus_skip">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="enable to be the focused surface">
+        This request makes the given surface enable to be the focused surface.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="set_role">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
-      <arg name="role" type="string"/>
+      <description summary="set the role of the surface">
+        Give the role to the given surface. A client set the tizen-specific role
+        of the surface except for the role of xdg_surface interface,
+        xdg_top_level, xdg_popup and so on.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="role" type="string" summary="the name of the role"/>
     </request>
 
     <enum name="win_type">
-      <entry name="none" value="0"/>
-      <entry name="toplevel" value="1"/>
-      <entry name="fullscreen" value="2"/>
-      <entry name="maximized" value="3"/>
-      <entry name="transient" value="4"/>
-      <entry name="menu" value="5"/>
-      <entry name="dnd" value="6"/>
-      <entry name="custom" value="7"/>
-      <entry name="notification" value="8"/>
-      <entry name="utility" value="9"/>
-      <entry name="dialog" value="10"/>
-      <entry name="dock" value="11"/>
-      <entry name="splash" value="12"/>
-      <entry name="desktop" value="13" since="11"/>
+      <description summary="window type of the surface">
+        A client can set the window type through the set_type request with
+        win_type values. The value gives the surface the window_state, the
+        z-order at the window stack in the window layer and other types in the
+        display server.
+
+        The following values are window types with z-order values in descending
+        order. Those are notification, dnd, dock, splash, fullscreen,
+        toplevel or maximized and desktop.
+        The menu, dnd, notification, utility, dialog, dock, splash and desktop
+        are the window type which is defined in netwm spefification.
+        https://specifications.freedesktop.org/wm-spec/wm-spec-1.4.html#idm46148902270160
+      </description>
+      <entry name="none" value="0" summary="none"/>
+      <entry name="toplevel" value="1" summary="the toplevel"/>
+      <entry name="fullscreen" value="2" summary="the fullscreen state"/>
+      <entry name="maximized" value="3" summary="the maximize state"/>
+      <entry name="transient" value="4" summary="the transient relation state"/>
+      <entry name="menu" value="5" summary="the menu"/>
+      <entry name="dnd" value="6" summary="the dnd"/>
+      <entry name="custom" value="7" summary="the custom"/>
+      <entry name="notification" value="8" summary="the notification"/>
+      <entry name="utility" value="9" summary="the utility"/>
+      <entry name="dialog" value="10" summary="the dialog"/>
+      <entry name="dock" value="11" summary="the dock"/>
+      <entry name="splash" value="12" summary="the splash"/>
+      <entry name="desktop" value="13" since="11" summary="the desktop"/>
     </enum>
 
     <request name="set_type">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="win_type" type="uint" />
+      <description summary="set the type of the surface">
+        Set the type of the given surface. The display server use the window
+        type for the policy of the window management which are focus management,
+        visibility management, stack management and so on.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="win_type" type="uint" summary="the window type"/>
     </request>
 
     <!-- for conformant -->
     <request name="set_conformant">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="set the conformant(adaptational) surface">
+        Set the conformant surface. The conformant surface can get the event
+        through which the display server notifies the area covered by the
+        compormant_part that is the surface in another client.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="unset_conformant">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="unset the conformant(adaptational) surface">
+        Unset the conformant surface.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="get_conformant">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="check the conformant surface">
+        Ask if the given surface is the conformant surface or not. The display
+        server sents the result via the confirmant event.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <event name="conformant">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
-      <arg name="is_conformant" type="uint"/>
+      <description summary="conformant event">
+        Notify the client when a client sends the get_conformant request.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="is_conformant" type="uint" summary="if the surface is conformant or not, 0 or 1"/>
     </event>
 
     <enum name="conformant_part">
-      <entry name="indicator" value="0"/>
-      <entry name="keyboard" value="1"/>
-      <entry name="clipboard" value="2"/>
+      <description summary="the name of conformant part">
+        This value indicates the surface name at Tizen Platform.
+      </description>
+      <entry name="indicator" value="0" summary="the indicator surface"/>
+      <entry name="keyboard" value="1" summary="the keyboard surface"/>
+      <entry name="clipboard" value="2" summary="the clipboard surface"/>
     </enum>
 
     <event name="conformant_area">
-       <description summary="Notify of conformant area">
-          Notify of conformant area to client. Sending this event does NOT guarantee
-          perfect compositing of conformant owner client surface and
-          conformant part client surface.
-      </description>
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
-      <arg name="conformant_part" type="uint"/>
-      <arg name="state" type="uint"/>
-      <arg name="x" type="int"/>
-      <arg name="y" type="int"/>
-      <arg name="w" type="int"/>
-      <arg name="h" type="int"/>
+      <description summary="conformant area event">
+        Notify a client when the conformant area is caclulated by the another
+        surface as the conformnat_part. This event does NOT guarantee the
+        perfect composition of the conformant surface and the surface of the
+        conformant part.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="conformant_part" type="uint" summary="the name of the conformant part"/>
+      <arg name="state" type="uint" summary="visible(1) or not(0)"/>
+      <arg name="x" type="int" summary="x position of the hiding area by conformant part"/>
+      <arg name="y" type="int" summary="y position of the hiding area by conformant part"/>
+      <arg name="w" type="int" summary="width of the hiding area by conformant part"/>
+      <arg name="h" type="int" summary="height of the hiding area by conformant part"/>
     </event>
 
     <enum name="error_state">
-      <entry name="none" value="0"/>
-      <entry name="permission_denied" value="1"/>
+      <description summary="error state">
+        This describes the state of error.
+      </description>
+      <entry name="none" value="0" summary="success"/>
+      <entry name="permission_denied" value="1" summary="the permission denied"/>
     </enum>
 
     <!-- for notification -->
     <enum name="level">
-      <entry name="1" value="0"/>
-      <entry name="2" value="1"/>
-      <entry name="3" value="2"/>
-      <entry name="none" value="-1"/>
-      <entry name="default" value="10"/>
-      <entry name="medium" value="20"/>
-      <entry name="high" value="30"/>
-      <entry name="top" value="40"/>
+      <description summary="notification level">
+        This is the level of the notification type. This level stands for the
+        z-order in the notification layer at the display server. The none, 1, 2,
+        3, default, medium, high and top is z-order in ascending order. The
+        lower number value means the lower z-order.
+      </description>
+      <entry name="1" value="0" summary="the bottom default z-order"/>
+      <entry name="2" value="1" summary="the bottom midium z-order"/>
+      <entry name="3" value="2" summary="the bottom high z-order"/>
+      <entry name="none" value="-1" summary="the bottom lowest z-order"/>
+      <entry name="default" value="10" summary="the default z-order"/>
+      <entry name="medium" value="20" summary="the medium z-order"/>
+      <entry name="high" value="30" summary="the high z-order"/>
+      <entry name="top" value="40" summary="the top z-order"/>
     </enum>
 
     <request name="set_notification_level">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="level" type="int"/>
+      <description summary="set the level in the notification">
+        This request sets the level in the notification layer. The display
+        server decides the z-order with the given level in the notification
+        layer.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="level" type="int" summary="the z-order value"/>
     </request>
 
     <event name="notification_done">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="level" type="int"/>
-      <arg name="error_state" type="uint"/>
+      <description summary="done event of set_notification request">
+        Notify a client when the surface is located in the z-order which has
+        been reuqested via the set_notification_level request.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="level" type="int" summary="the z-order value"/>
+      <arg name="error_state" type="uint" summary="the error type"/>
     </event>
 
     <!-- for transient_for -->
     <request name="set_transient_for">
-      <arg name="child_id" type="uint" />
-      <arg name="parent_id" type="uint" />
+      <description summary="set the transient parent for parent_id">
+        This request sets the transient parent for the surface associated with
+        the parent_id. The surface associated with the given child_id becomes
+        a transient children for the surface associated with the parent_id.
+      </description>
+      <arg name="child_id" type="uint" summary="the global resource id for the child surface"/>
+      <arg name="parent_id" type="uint" summary="the globacl resource is for the parent surface"/>
     </request>
 
     <request name="unset_transient_for">
-      <arg name="child_id" type="uint" />
+      <description summary="unset the transient parent/child relationship">
+        This reuqest unsets the transient parent on the surface associated with
+        the child_id.
+      </description>
+      <arg name="child_id" type="uint" summary="the global resource id for the child surface"/>
     </request>
 
     <event name="transient_for_done">
-      <arg name="child_id" type="uint"/>
+      <description summary="done event of set/unset transient_for">
+        Notify a client when the surface associated with the child_id is to set
+        the transient parent or when it is to unset the transient parent.
+      </description>
+      <arg name="child_id" type="uint" summary="the global resource id for the child surface"/>
     </event>
 
     <!-- for window_screen_mode -->
     <enum name="mode">
-      <entry name="default" value="0"/>
-      <entry name="always_on" value="1"/>
+      <description summary="screen mode">
+        This value means how the screen is to operate.
+      </description>
+      <entry name="default" value="0" summary="the default screen mode"/>
+      <entry name="always_on" value="1" summary="keep the screen turn on"/>
     </enum>
 
     <request name="set_window_screen_mode">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="mode" type="uint"/>
+      <description summary="set the screen mode to the surface">
+        A client sets the screen mode which it wants the screen to be as long as
+        the given surface is shown on the screen.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="mode" type="uint" summary="the screen mode"/>
     </request>
 
     <event name="window_screen_mode_done">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="mode" type="uint"/>
-      <arg name="error_state" type="uint"/>
+      <description summary="done event for set_window_screen_mode request">
+        Notify a client when the screen_mode from the client's request activates
+        in the display server.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="mode" type="uint" summary="the screen mode"/>
+      <arg name="error_state" type="uint" summary="the error type"/>
     </event>
 
     <!-- for subsurface -->
     <request name="place_subsurface_below_parent">
-      <arg name="subsurface" type="object" interface="wl_subsurface"/>
+      <description summary="place the subsurace below the parent surface">
+        This request places the surface of the subsurface below its' parent
+        surface.
+      </description>
+      <arg name="subsurface" type="object" interface="wl_subsurface" summary="the subsurface object"/>
     </request>
 
     <request name="set_subsurface_stand_alone">
-      <arg name="subsurface" type="object" interface="wl_subsurface"/>
+      <description summary="make the subsurface be a stand_alone mode">
+        This request makes the surface associated with the given subsurface not
+        follow the policy of the window managment triggered by the parent
+        surface. The window policy of the surface associated with the given
+        subsurface is not affected by its parent surface.
+      </description>
+      <arg name="subsurface" type="object" interface="wl_subsurface" summary="the subsurface object"/>
     </request>
 
     <request name="get_subsurface">
-      <arg name="id" type="new_id" interface="wl_subsurface" />
-      <arg name="surface" type="object" interface="wl_surface" />
-      <arg name="parent_id" type="uint" />
+      <description summary="get the subsurface of the surface with the parent_id">
+          Get the subsurface of the given surface with the global resource parent_id.
+      </description>
+      <arg name="id" type="new_id" interface="wl_subsurface" summary="the new subsurface object"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="parent_id" type="uint" summary="the global reosurce id"/>
     </request>
 
     <!-- for opaque_state -->
     <request name="set_opaque_state">
-      <arg name="surface" type="object" interface="wl_surface" />
+      <description summary="set the opaque state to the surface">
+      Set the opaque state to the given surface. The display server makes this
+      surface be opaque even if the color depth of the buffer attached to the
+      surface is 32 depth.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
       <arg name="state" type="int"/>
     </request>
 
     <!-- for iconify -->
     <request name="iconify">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="set the iconified state to the surface">
+        Set the iconified state to the given surface. The iconfied state is the
+        window state in which the surface is not showing on the screen.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
+
     <request name="uniconify">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="set the uniconified state to the surface">
+        Set the uniconified state to the given surface. The uniconfied state is
+        the window state in which the iconified surface is showing on the screen.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <event name="iconify_state_changed">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="iconified" type="uint"/>
-      <arg name="force" type="uint"/>
+      <description summary="change event of the iconfied state">
+        Notify a client when the iconfied state of the surface is changed. The
+        iconfied state is not only changed when the client requets the iconify
+        and uniconify but also changed when the iconfied state is decided by
+        the display server.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="iconified" type="uint" summary="the iconfied or uniconified state, 1 or 0"/>
+      <arg name="force" type="uint" summary="the iconfied is forced or not, 1 or 0"/>
     </event>
 
     <!-- for aux_hint -->
     <request name="add_aux_hint">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="id" type="int" />
-      <arg name="name" type="string" />
-      <arg name="value" type="string" />
+      <description summary="add the information of the auxiliary hint to the surface">
+        Add the information of the auxiliary hint to the given surface. The name
+        and the value are changed when the display server already has the same
+        id with which the client sends this request.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="id" type="int" summary="the id of the auxiliary hint"/>
+      <arg name="name" type="string" summary="the name of the auxiliary hint"/>
+      <arg name="value" type="string" summary="the vaule of the auxiliary hint"/>
     </request>
 
     <request name="change_aux_hint">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="id" type="int" />
-      <arg name="value" type="string" />
+      <description summary="change the value of the auxiliary hint to the surface">
+        Change the value of the auxiliary hint id which the surface has.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="id" type="int" summary="the id of the auxiliary hint"/>
+      <arg name="value" type="string" summary="the vaule of the auxiliary hint"/>
     </request>
 
     <request name="del_aux_hint">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="id" type="int" />
+      <description summary="delete the information of the auxiliry hint">
+        Delete the information of the auxiliary hint associated the hint id
+        which the given surface has.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="id" type="int" summary="the id of the auxiliary hint"/>
     </request>
 
     <request name="get_supported_aux_hints">
-      <arg name="surface" type="object" interface="wl_surface"/>
+      <description summary="get the aux hints">
+        Get the ids of the aux hints which the given surface supports. The
+        display server send the supported_aux_hints events as the reply of this
+        requrest.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <event name="supported_aux_hints">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="hints" type="array" />
-      <arg name="num_hints" type="uint"/>
+      <description summary="reply event for the get_supported_aux_hints request">
+        Notify a client when the display server get the get_supported_aux_hints
+        request. The display server send the id array of the suxiliary hints
+        which the surface supports.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="hints" type="array" summary="the id array of the auxiliary hints"/>
+      <arg name="num_hints" type="uint" summary="the number of hints"/>
     </event>
 
     <event name="allowed_aux_hint">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="id" type="int" />
+      <description summary="event of the allowed auxiliary hint">
+        Notify a client when the auxiliary hint which the given surface has is
+        added and changed.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="id" type="int" summary="the id of the auxiliary hint"/>
     </event>
 
     <!-- for aux_message -->
     <event name="aux_message">
-      <arg name="surface" type="object" interface="wl_surface" />
-      <arg name="key" type="string" />
-      <arg name="value" type="string" />
-      <arg name="options" type="array" />
+      <description summary="the auxiliary message event">
+        Notify a client when the display server sends the auxiliary message.
+        The display server can use this event when it notifies an additional
+        information to the client.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="key" type="string" summary="the key string"/>
+      <arg name="value" type="string" summary="the vaule of the key"/>
+      <arg name="options" type="array" summary="the array of option information"/>
     </event>
 
     <!-- for background state -->
     <request name="set_background_state">
-       <arg name="pid" type="uint" />
+      <description summary="set the background state">
+        Set the all surfaces associated with the given pid to be the background
+        state. The surfaces set to be the hide state and cannot show on a screen
+        even if the client send the show request and the activate request.
+      </description>
+       <arg name="pid" type="uint" summary="the process id"/>
     </request>
 
     <request name="unset_background_state">
-       <arg name="pid" type="uint" />
+      <description summary="unset the background state">
+        Set the all surfaces associated with the given pid not to be the
+        background state. The sufaces can allow to be showed and to be activated
+        by the client's request.
+      </description>
+       <arg name="pid" type="uint" summary="the process id"/>
     </request>
 
     <!-- for floating mode -->
     <request name="set_floating_mode">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="set the floating mode">
+        Set the floating mode to the given surface. The surface which sets to be
+        floating mode can be a partial window and can position over other
+        top-level windows.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="unset_floating_mode">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="unset the floating mode">
+        Unset the floating mode to the given surface. The geometry of the
+        surface does not change and the z-order of it can be the same as the
+        top-level windows.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <!-- for stack mode -->
     <enum name="stack_mode">
+      <description summary="mode for the relative stack order">
+        The set_stack_mode request uses this mode values.
+      </description>
       <entry name="none" value="0"/>
       <entry name="above" value="1"/>
       <entry name="below" value="2"/>
     </enum>
 
     <request name="set_stack_mode">
-      <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="mode" type="uint" />
+      <description summary="set the stack mode">
+        Set the stack mode to the given surface. The surface can changes the
+        z-order in the same layer by the stack mode.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="mode" type="uint" summary="the stack mode"/>
     </request>
 
     <request name="activate_above_by_res_id">
-      <arg name="res_id" type="uint" />
-      <arg name="above_res_id" type="uint" />
+      <description summary="activate and position over the above resource id">
+        Activate the surface associated with the given res_id which is the
+        global resource id and set to position over the surface assoicated with
+        the above_res_id.
+      </description>
+      <arg name="res_id" type="uint" summary="the global resource id"/>
+      <arg name="above_res_id" type="uint" summary="the globacl resource id"/>
     </request>
 
     <!-- version 2 additions -->
     <!-- for subsurface watcher -->
     <request name="get_subsurface_watcher" since="2">
-      <arg name="id" type="new_id" interface="tizen_subsurface_watcher" />
-      <arg name="surface" type="object" interface="wl_surface" />
+      <description summary="get the subsurface watcher">
+        Get the subsurface watcher associated with the given surface. A client
+        can get the information about the subsurface associated with the surface.
+      </description>
+      <arg name="id" type="new_id" interface="tizen_subsurface_watcher" summary="new tizen_subsurface_watcher object"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <!-- version 3 additions -->
     <request name="set_parent" since="3">
-      <arg name="child" type="object" interface="wl_surface" />
-      <arg name="parent" type="object" interface="wl_surface" />
+      <description summary="set the parent">
+        Set the parent/client relationship. The child surface position over the
+        parent surface.
+      </description>
+      <arg name="child" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="parent" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <!-- version 4 additions -->
@@ -342,53 +587,71 @@
          If client is received this event, client should ack for it using
          tizen_policy@ack_conformant_region request.
       </description>
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
-      <arg name="conformant_part" type="uint"/>
-      <arg name="state" type="uint"/>
-      <arg name="x" type="int"/>
-      <arg name="y" type="int"/>
-      <arg name="w" type="int"/>
-      <arg name="h" type="int"/>
-      <arg name="serial" type="uint"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="conformant_part" type="uint" summary="the name of the conformant part"/>
+      <arg name="state" type="uint" summary="visible(1) or not(0)"/>
+      <arg name="x" type="int" summary="x position of the hiding area by conformant part"/>
+      <arg name="y" type="int" summary="y position of the hiding area by conformant part"/>
+      <arg name="w" type="int" summary="width of the hiding area by conformant part"/>
+      <arg name="h" type="int" summary="height of the hiding area by conformant part"/>
+      <arg name="serial" type="uint" summary="serail number"/>
     </event>
 
     <request name="ack_conformant_region" since="4">
       <description summary="ack for tizen_policy@conformant_region">
-         A client can refresh its surface for applying new conformant region which
-         is from tizen_policy@conformant_region event. The client has to ack
-         after complete of its updates by this request.
+         A client can refresh its surface for applying new conformant region
+         which is from tizen_policy@conformant_region event. The client has to
+         ack after complete of its updates by this request.
       </description>
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
-      <arg name="serial" type="uint"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="serial" type="uint" summary="serial number"/>
     </request>
 
     <request name="destroy" type="destructor" since="6">
       <description summary="destroy the tizen_policy">
-        Destroy the tizen_policy.
+        Destroy this tizen_policy object.
       </description>
     </request>
 
     <request name="has_video" since="7">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
-      <arg name="has" type="uint"/>
+      <description summary="check the tizen_video_object">
+        A cleint sends the information that it has the tizen_video_object to the
+        display server.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
+      <arg name="has" type="uint" summary="1 is the tizen_video_object, or 0"/>
     </request>
 
     <request name="set_appid" since="7">
-       <arg name="pid" type="int" />
-       <arg name="appid" type="string" />
+      <description summary="set the application id">
+        Set the application id associated with the given pid.
+      </description>
+       <arg name="pid" type="int" summary="process id"/>
+       <arg name="appid" type="string" summary="application id"/>
     </request>
 
     <request name="show" since="8">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="notify showing the surface">
+        Notify showing the given surface. This request means that a client is
+        going to attach the buffer to the given surface. There is nothing to do
+        at the display server when a client sends this request.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="hide" since="8">
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <description summary="notify hiding the surface">
+        Notify hiding the given surface. This request means that a client is
+        going to attach the null buffer to the given surface. There is nothing
+        to do at the display server when a client sends this request.
+      </description>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
     </request>
 
     <request name="set_transient_for_below" since="9">
       <description summary="set transient_for and place under the transient_for parent">
-         This makes a relationship between parent and child. A child is always placed under a parent.
+         This makes a relationship between parent and child. A child is always
+         placed under a parent.
       </description>
       <arg name="child_id" type="uint" />
       <arg name="parent_id" type="uint" />
@@ -396,19 +659,20 @@
 
     <request name="set_parent_with_below" since="9">
       <description summary="set parent and place under the parent">
-         This makes a relationship between parent and child. A child is always placed under a parent.
-         Setting a null parent for a child window removes any parent-child relationship for the child.
+         This makes a relationship between parent and child. A child is always
+         placed under a parent. Setting a null parent for a child window removes
+         any parent-child relationship for the child.
       </description>
-      <arg name="child" type="object" interface="wl_surface" />
+      <arg name="child" type="object" interface="wl_surface" summary="the surface object"/>
       <arg name="parent" type="object" interface="wl_surface" allow-null="true"/>
     </request>
 
     <event name="interactive_move_done" since="10">
       <description summary="interactive move is done">
-         This event is sent when the display server finishes interactive moving the window.
-         The changed geometry of the window is sent together.
+         This event is sent when the display server finishes interactive moving
+         the window. The changed geometry of the window is sent together.
       </description>
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
       <arg name="x" type="int" summary="x-position after move"/>
       <arg name="y" type="int" summary="y-position after move"/>
       <arg name="w" type="uint" summary="width after move"/>
@@ -418,10 +682,11 @@
 
     <event name="interactive_resize_done" since="10">
       <description summary="interactive resize is done">
-         This event is sent when the display server finishes interactive resizing the window.
-         The changed geometry of the window is sent together.
+         This event is sent when the display server finishes interactive
+         resizing the window. The changed geometry of the window is sent
+         together.
       </description>
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
       <arg name="x" type="int" summary="x-position after resize"/>
       <arg name="y" type="int" summary="y-position after resize"/>
       <arg name="w" type="uint" summary="width after resize"/>
@@ -431,6 +696,9 @@
 
     <!-- for maximize direction -->
     <enum name="maximize_direction">
+      <description summary="direction values">
+        These values are used by the set_maximize_direction as the paremater.
+      </description>
       <entry name="none" value="0" summary="none. same to unmaximize"/>
       <entry name="all" value="1" summary="the full size of the screen"/>
       <entry name="left" value="2" summary="the left side of the screen"/>
@@ -443,29 +711,48 @@
       <description summary="set maximize direction">
          Set the maximize direction of the surface.
       </description>
-      <arg name="surface" type="object" interface="wl_surface" summary="surface object"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="the surface object"/>
       <arg name="direction" type="uint" enum="maximize_direction" summary="maximize direction"/>
     </request>
 
   </interface>
 
   <interface name="tizen_visibility" version="5">
-    <request name="destroy" type="destructor"/>
+    <description summary="tizen-specific visibility">
+      A client wants to know the visiblity information of the surface.
+    </description>
 
-    <enum name="visibility">
-      <entry name="unobscured" value="0"/>
-      <entry name="partially_obscured" value="1"/>
-      <entry name="fully_obscured" value="2"/>
-      <entry name="pre_unobscured" value="3" since="5"/>
-    </enum>
+    <request name="destroy" type="destructor">
+      <description summary="destroy the tizen_visibility">
+        Destroy this tizen_visiblity object.
+      </description>
+    </request>
+
+      <enum name="visibility">
+        <description summary="visibility type">
+          These are the visibilty types which tells how the surface assoicated
+          with the tizen_visibility resource is showing on a screen or not.
+        </description>
+        <entry name="unobscured" value="0" summary="fully showing on a screen"/>
+        <entry name="partially_obscured" value="1" summary="partially showing on a screen"/>
+        <entry name="fully_obscured" value="2" summary="not showing on a screen"/>
+        <entry name="pre_unobscured" value="3" since="5" summary="ready to be unobscured"/>
+      </enum>
 
     <event name="notify">
-      <arg name="visibility" type="uint"/>
+      <description summary="notify the visiblity state">
+        Notify a client when the visibility of the surface is changed.
+      </description>
+      <arg name="visibility" type="uint" summary="visiblity type"/>
     </event>
 
     <!-- Version 6 additions -->
 
     <event name="changed" since="5">
+      <description summary="notify the changed visiblity type">
+        Notify a client when the visibility of the surface is changed with the
+        extra vaule.
+      </description>
       <arg name="type" type="uint" enum="visibility" summary="changed visibility type"/>
       <arg name="option" type="uint" summary="extra value"/>
     </event>
@@ -473,16 +760,30 @@
   </interface>
 
   <interface name="tizen_position" version="1">
-    <request name="destroy" type="destructor"/>
+    <description summary="tizen-specific position">
+      A client can set the position information of the surface.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the tizen_position">
+        Destroy this tizen_position object.
+      </description>
+    </request>
 
     <request name="set">
-      <arg name="x" type="int"/>
-      <arg name="y" type="int"/>
+      <description summary="set the position">
+        Set the position.
+      </description>
+      <arg name="x" type="int" summary="x position"/>
+      <arg name="y" type="int" summary="y position"/>
     </request>
 
     <event name="changed">
-      <arg name="x" type="int"/>
-      <arg name="y" type="int"/>
+      <description summary="event of position changed">
+        Notify a client when the posion is changed.
+      </description>
+      <arg name="x" type="int" summary="x position"/>
+      <arg name="y" type="int" summary="y position"/>
     </event>
   </interface>