add doxygen document

Change-Id: I41cdc17d84206dc473369f7f9145b5cb35f82ead

diff --git a/client/tdm_client.h b/client/tdm_client.h
index 58221e0..bceecc1 100644 (file)
--- a/client/tdm_client.h
+++ b/client/tdm_client.h
@@ -42,13 +42,16 @@ extern "C" {
 
 /**
  * @file tdm_client.h
- * @brief The header file for a client user of TDM.
+ * @brief The header file for a client of TDM.
  * @par Example
  * @code
-   #include <tdm_client.h>    //for a client user of TDM
+   #include <tdm_client.h>    //for a client of TDM
  * @endcode
  */
 
+/**
+ * @brief The client error enumeration
+ */
 typedef enum
 {
        TDM_CLIENT_ERROR_NONE                  = 0,  /**< none */
@@ -58,24 +61,99 @@ typedef enum
        TDM_CLIENT_ERROR_OUT_OF_MEMORY         = -4, /**< no free memory */
 } tdm_client_error;
 
+/**
+ * @brief The TDM client object
+ */
 typedef void *tdm_client;
 
+/**
+ * @brief The client vblank handler
+ * @see #tdm_client_wait_vblank
+ */
 typedef void
 (*tdm_client_vblank_handler)(unsigned int sequence, unsigned int tv_sec,
                              unsigned int tv_usec, void *user_data);
 
+/**
+ * @brief Create a TDM client object.
+ * @param[out] error #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value.
+ * @return A TDM client object if success. Otherwise, NULL.
+ * @see #tdm_client_destroy
+ */
 tdm_client*
 tdm_client_create(tdm_client_error *error);
 
+/**
+ * @brief Destroy a TDM client object
+ * @param[in] client A TDM client object
+ * @see #tdm_client_create
+ */
 void
 tdm_client_destroy(tdm_client *client);
 
+/**
+ * @brief Get the file descriptor
+ * @param[in] client A TDM client object
+ * @param[out] fd The file descriptor
+ * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value.
+ * @see #tdm_client_handle_events
+ * @par Example
+ * @code
+   #include <tdm_client.h>    //for a client of TDM
+
+   err = tdm_client_get_fd(client, &fd);
+   if (err != TDM_CLIENT_ERROR_NONE) {
+       //error handling
+   }
+
+   fds.events = POLLIN;
+   fds.fd = fd;
+   fds.revents = 0;
+
+   while(1) {
+      ret = poll(&fds, 1, -1);
+      if (ret < 0) {
+         if (errno == EBUSY)
+            continue;
+         else {
+            //error handling
+         }
+      }
+
+      err = tdm_client_handle_events(client);
+      if (err != TDM_CLIENT_ERROR_NONE) {
+          //error handling
+      }
+   }
+ * @endcode
+ */
 tdm_client_error
 tdm_client_get_fd(tdm_client *client, int *fd);
 
+/**
+ * @brief Handle the events of the given file descriptor
+ * @param[in] client A TDM client object
+ * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value.
+ * @see #tdm_client_get_fd
+ */
 tdm_client_error
 tdm_client_handle_events(tdm_client *client);
 
+/**
+ * @brief Wait for VBLANK
+ * @details After interval vblanks, a client vblank handler will be called.
+ * If 'sw_timer' param is 1, TDM will use the SW timer and call a client vblank
+ * handler when DPMS off.
+ * @param[in] client A TDM client object
+ * @param[in] name The name of a TDM output
+ * @param[in] sw_timer 0: not using SW timer, 1: using SW timer
+ * @param[in] interval vblank interval
+ * @param[in] sync 0: asynchronous, 1:synchronous
+ * @param[in] func A client vblank handler
+ * @param[in] user_data The user data
+ * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value.
+ * @see #tdm_client_vblank_handler
+ */
 tdm_client_error
 tdm_client_wait_vblank(tdm_client *client, char *name,
                        int sw_timer, int interval, int sync,