enhance doxgen document

Change-Id: Ie3e787772461d0c7922627176b8be5b9dc394305

diff --git a/client/tdm_client.h b/client/tdm_client.h
index 2f1c64f..c64391e 100644 (file)
--- a/client/tdm_client.h
+++ b/client/tdm_client.h
@@ -117,7 +117,7 @@ tdm_error
 tdm_client_handle_events(tdm_client *client);
 
 /**
- * @brief Wait for VBLANK
+ * @brief @b Deprecated. Wait for VBLANK.
  * @deprecated
  * @details After interval vblanks, a client vblank handler will be called.
  * If 'sw_timer' param is 1 in case of DPMS off, TDM will use the SW timer and
@@ -137,47 +137,241 @@ tdm_client_wait_vblank(tdm_client *client, char *name,
                                           int sw_timer, int interval, int sync,
                                           tdm_client_vblank_handler2 func, void *user_data);
 
-
+/**
+ * @brief Get the client output object which has the given name.
+ * @details
+ * The client output name can be @b 'primary' or @b 'default' to get the main output.
+ * @param[in] client The TDM client object
+ * @param[in] name The name of the TDM client output object
+ * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
+ * @return A client output object if success. Otherwise, NULL.
+ */
 tdm_client_output*
 tdm_client_get_output(tdm_client *client, char *name, tdm_error *error);
 
+/**
+ * @brief Add the client output change handler
+ * @details The handler will be called when the status of a
+ * client output object is changed. connection, DPMS, etc.
+ * @param[in] output The client output object
+ * @param[in] func The client output change handler
+ * @param[in] user_data The user data
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ * @par Example
+ * @code
+ * #include <tdm_client.h>    //for a client of TDM
+ *
+ * static void
+ * _client_output_handler(tdm_client_output *output, tdm_output_change_type type,
+ *                        tdm_value value, void *user_data)
+ * {
+ *     char *conn_str[3] = {"disconnected", "connected", "mode_setted"};
+ *     char *dpms_str[4] = {"on", "standy", "suspend", "off"};
+ *
+ *     if (type == TDM_OUTPUT_CHANGE_CONNECTION)
+ *         printf("output %s.\n", conn_str[value.u32]);
+ *     else if (type == TDM_OUTPUT_CHANGE_DPMS)
+ *         printf("dpms %s.\n", dpms_str[value.u32]);
+ * }
+ * ...
+ * tdm_client_output_add_change_handler(output, _client_output_handler, NULL);
+ * ...
+ * tdm_client_output_remove_change_handler(output, _client_output_handler, NULL);
+ *
+ * @endcode
+ */
 tdm_error
 tdm_client_output_add_change_handler(tdm_client_output *output,
                                                                         tdm_client_output_change_handler func,
                                                                         void *user_data);
 
+/**
+ * @brief Remove the client output change handler
+ * @param[in] output The client output object
+ * @param[in] func The client output change handler
+ * @param[in] user_data The user data
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ */
 void
 tdm_client_output_remove_change_handler(tdm_client_output *output,
                                                                                tdm_client_output_change_handler func,
                                                                                void *user_data);
 
+/**
+ * @brief Get the vertical refresh rate of the given client output
+ * @param[in] output The client output object
+ * @param[out] refresh The refresh rate
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ */
 tdm_error
 tdm_client_output_get_refresh_rate(tdm_client_output *output, unsigned int *refresh);
 
+/**
+ * @brief Get the connection status of the given client output
+ * @param[in] output The client output object
+ * @param[out] status The connection status
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ */
 tdm_error
 tdm_client_output_get_conn_status(tdm_client_output *output, tdm_output_conn_status *status);
 
+/**
+ * @brief Get the DPMS value of the given client output
+ * @param[in] output The client output object
+ * @param[out] dpms The DPMS value
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ */
 tdm_error
 tdm_client_output_get_dpms(tdm_client_output *output, tdm_output_dpms *dpms);
 
+/**
+ * @brief Create the client vblank object of the given client output
+ * @param[in] output The client output object
+ * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
+ * @return A client vblank object if success. Otherwise, NULL.
+ */
 tdm_client_vblank*
 tdm_client_output_create_vblank(tdm_client_output *output, tdm_error *error);
 
+/**
+ * @brief Destroy the client vblank object
+ * @param[in] vblank The client vblank object
+ */
 void
 tdm_client_vblank_destroy(tdm_client_vblank *vblank);
 
+/**
+ * @brief Set the sync value to the client vblank object
+ * @details
+ * If sync == 1, the user client vblank handler of #tdm_client_vblank_wait
+ * will be called before #tdm_client_vblank_wait returns the result. If sync == 0,
+ * the user client vblank handler of #tdm_client_vblank_wait will be called
+ * asynchronously after #tdm_client_vblank_wait returns. Default is @b asynchronous.
+ * @param[in] vblank The client vblank object
+ * @param[in] sync 0: asynchronous, 1:synchronous
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ */
 tdm_error
 tdm_client_vblank_set_sync(tdm_client_vblank *vblank, unsigned int sync);
 
+/**
+ * @brief Set the fps to the client vblank object
+ * @details Default is the @b vertical @b refresh @b rate of the given client output.
+ * @param[in] vblank The client vblank object
+ * @param[in] fps more than 0
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ */
 tdm_error
 tdm_client_vblank_set_fps(tdm_client_vblank *vblank, unsigned int fps);
 
+/**
+ * @brief Set the offset(milli-second) to the client vblank object
+ * @details Default is @b 0.
+ * @param[in] vblank The client vblank object
+ * @param[in] offset_ms the offset(milli-second)
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ */
 tdm_error
 tdm_client_vblank_set_offset(tdm_client_vblank *vblank, int offset_ms);
 
+/**
+ * @brief Enable/Disable the fake vblank to the client vblank object
+ * @details
+ * If enable_fake == 0, #tdm_client_vblank_wait will return TDM_ERROR_DPMS_OFF
+ * when DPMS off. Otherwise, #tdm_client_vblank_wait will return TDM_ERROR_NONE
+ * as success. Once #tdm_client_vblank_wait returns TDM_ERROR_NONE, the user client
+ * vblank handler(#tdm_client_vblank_handler) SHOULD be called after the given
+ * interval of #tdm_client_vblank_wait. Default is @b disable.
+ * @param[in] vblank The client vblank object
+ * @param[in] enable_fake 1:enable, 0:disable
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ */
 tdm_error
 tdm_client_vblank_set_enable_fake(tdm_client_vblank *vblank, unsigned int enable_fake);
 
+/**
+ * @brief Wait for a vblank
+ * @details
+ * This function will return TDM_ERROR_DPMS_OFF when DPMS off. However,
+ * #tdm_client_vblank_wait will return TDM_ERROR_NONE as success if
+ * #tdm_client_vblank_set_enable_fake sets true. Once #tdm_client_vblank_wait
+ * returns TDM_ERROR_NONE, the user client vblank handler(#tdm_client_vblank_handler)
+ * SHOULD be called after the given interval.
+ * @param[in] vblank The client vblank object
+ * @param[in] interval The vblank interval
+ * @param[in] func The user client vblank handler
+ * @param[in] user_data The user data
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ * @par Example
+ * @code
+ * #include <tdm_client.h>    //for a client of TDM
+ *
+ * static void
+ * _client_vblank_handler(tdm_client_vblank *vblank, tdm_error error, unsigned int sequence,
+ *                        unsigned int tv_sec, unsigned int tv_usec, void *user_data)
+ * {
+ *     if (error != TDM_ERROR_NONE)
+ *         //error handling
+ * }
+ *
+ * {
+ *     tdm_client_output *output;
+ *     tdm_client_vblank *vblank;
+ *     tdm_error error;
+ *     struct pollfd fds;
+ *     int fd = -1;
+ *
+ *     cliet = tdm_client_create(&error);
+ *     if (error != TDM_ERROR_NONE)
+ *         //error handling
+ *
+ *     output = tdm_client_get_output(client, NULL, &error);
+ *     if (error != TDM_ERROR_NONE)
+ *         //error handling
+ *
+ *     vblank = tdm_client_output_create_vblank(output, &error);
+ *     if (error != TDM_ERROR_NONE)
+ *         //error handling
+ *
+ *     tdm_client_vblank_set_enable_fake(vblank, enable_fake); //default: disable
+ *     tdm_client_vblank_set_sync(vblank, 0); //default: async
+ *     tdm_client_vblank_set_fps(vblank, fps); //default: refresh rate of output
+ *     tdm_client_vblank_set_offset(vblank, offset); //default: 0
+ *
+ *     error = tdm_client_get_fd(data->client, &fd);
+ *     if (error != TDM_ERROR_NONE)
+ *         //error handling
+ *
+ *     fds.events = POLLIN;
+ *     fds.fd = fd;
+ *     fds.revents = 0;
+ *
+ *     while (1) {
+ *         int ret;
+ *
+ *         error = tdm_client_vblank_wait(vblank, interval,
+ *                                        _client_vblank_handler, NULL);
+ *         if (error != TDM_ERROR_NONE)
+ *             //error handling
+ *
+ *         ret = poll(&fds, 1, -1);
+ *         if (ret < 0) {
+ *             if (errno == EINTR || errno == EAGAIN)  // normal case
+ *                 continue;
+ *             else
+ *                 //error handling
+ *         }
+ *
+ *         error = tdm_client_handle_events(client);
+ *         if (error != TDM_ERROR_NONE)
+ *             //error handling
+ *     }
+ *
+ *     tdm_client_vblank_destroy(vblank);
+ *     tdm_client_destroy(client);
+ * }
+ * @endcode
+ */
 tdm_error
 tdm_client_vblank_wait(tdm_client_vblank *vblank, unsigned int interval, tdm_client_vblank_handler func, void *user_data);
 

diff --git a/client/tdm_client_types.h b/client/tdm_client_types.h
index f6f6355..94807ec 100644 (file)
--- a/client/tdm_client_types.h
+++ b/client/tdm_client_types.h
@@ -87,6 +87,10 @@ typedef void tdm_client_output;
  */
 typedef void tdm_client_vblank;
 
+/**
+ * @brief The client output handler
+ * @see #tdm_client_output_add_change_handler, #tdm_client_output_remove_change_handler
+ */
 typedef void
 (*tdm_client_output_change_handler)(tdm_client_output *output,
                                                                        tdm_output_change_type type,
@@ -95,7 +99,7 @@ typedef void
 
 /**
  * @brief The client vblank handler
- * @see #tdm_client_wait_vblank
+ * @see #tdm_client_vblank_wait
  */
 typedef void
 (*tdm_client_vblank_handler)(tdm_client_vblank *vblank,

diff --git a/doc/Doxyfile b/doc/Doxyfile
index cd3a6a7..a5738ce 100644 (file)
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -104,7 +104,10 @@ INPUT                  = \
     include/tdm_helper.h \
     include/tdm_list.h \
     include/tdm_log.h \
-    include/tdm_types.h
+    include/tdm_types.h \
+    include/tdm_common.h \
+    client/tdm_client_types.h \
+    client/tdm_client.h
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO

diff --git a/protocol/tdm.xml b/protocol/tdm.xml
index 308fe8c..cb161b5 100644 (file)
--- a/protocol/tdm.xml
+++ b/protocol/tdm.xml
@@ -9,13 +9,17 @@
         </description>
 
         <request name="create_output">
-            <arg name="name" type="string" summary="output's name"/>
+            <arg name="name" type="string" summary="output's name. 'primary' or 'default' can be used for default."/>
             <arg name="id" type="new_id" interface="wl_tdm_output"/>
         </request>
 
     </interface>
 
     <interface name="wl_tdm_output" version="1">
+        <description summary="TDM client output object">
+      When the DPMS of connection status of the output is changed, TDM server
+      will send wl_tdm_output.mode and wl_tdm_output.dpms event.
+        </description>
 
         <event name="mode">
             <arg name="width" type="uint"/>
@@ -43,9 +47,9 @@
 
         <event name="done">
             <arg name="req_id" type="uint" summary="wait_vblank request ID"/>
-            <arg name="sequence" type="uint" summary="sequence of the HW vblank"/>
-            <arg name="tv_sec" type="uint" summary="sec of the HW vblank in kernel side"/>
-            <arg name="tv_usec" type="uint" summary="usec of the HW vblank in kernel side"/>
+            <arg name="sequence" type="uint" summary="the sequence number of the vblank"/>
+            <arg name="tv_sec" type="uint" summary="sec of the vblank"/>
+            <arg name="tv_usec" type="uint" summary="usec of the vblank"/>
             <arg name="error" type="uint" summary="error status enumeration"/>
         </event>
 
@@ -65,9 +69,10 @@
 
         <request name="wait_vblank">
             <description summary="Wait for a HW vblank">
-          When wl_tdm_vblank.wait_vblank is called, TDM server will send the wl_tdm_vblank.done
-          event which is aligned with HW vblank. Even if DPMS is off, it will send
-          wl_tdm_vblank.done events by using SW timer.
+          When wl_tdm_vblank.wait_vblank is called, TDM server will send the
+          wl_tdm_vblank.done event after interval vblanks. If enable_fake == 1,
+          TDM server will send the done event always. Otherwise, TDM server will
+          send the done event with TDM error value.
             </description>
 
             <arg name="interval" type="uint"/>