Add description #2

diff --git a/include/wifi-aware.h b/include/wifi-aware.h
index a7cd658..244fc72 100644 (file)
--- a/include/wifi-aware.h
+++ b/include/wifi-aware.h
@@ -197,7 +197,7 @@ int wifi_aware_deinitialize();
 /**
  * @brief Create a Publish request.
  * @since_tizen 6.0
- * @param[out] publish
+ * @param[out] publish The Wi-Fi Aware Publish handle.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  * @see        wifi_aware_publish_destroy
@@ -207,7 +207,7 @@ int wifi_aware_publish_create(wifi_aware_publish_h *publish);
 /**
  * @brief Destroy a Publish request.
  * @since_tizen 6.0
- * @param[in] publish
+ * @param[in] publish  The Wi-Fi Aware Publish handle.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  * @see        wifi_aware_publish_create
@@ -217,6 +217,7 @@ int wifi_aware_publish_destroy(wifi_aware_publish_h publish);
 /**
  * @brief Create a Subscribe request.
  * @since_tizen 6.0
+ * @param[out] subscribe       The Wi-Fi Aware Subscribe handle.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  * @see        wifi_aware_subscribe_destroy
@@ -226,7 +227,7 @@ int wifi_aware_subscribe_create(wifi_aware_subscribe_h *subscribe);
 /**
  * @brief Destroy a Subscribe request.
  * @since_tizen 6.0
- * @param[in] subscribe
+ * @param[in] subscribe The Wi-Fi Aware Subscribe handle.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  * @see        wifi_aware_subscribe_create
@@ -234,10 +235,10 @@ int wifi_aware_subscribe_create(wifi_aware_subscribe_h *subscribe);
 int wifi_aware_subscribe_destroy(wifi_aware_subscribe_h subscribe);
 
 /**
- * @brief Sets TTL(Time To Live) to Publish configuration.
+ * @brief Sets TTL(Time To Live) for Publish session.
  * @since_tizen 6.0
- * @param[in] publish publish configuration handle.
- * @param[in] ttl lifetime(seconds) of publish session. 0 means forever until canceled.
+ * @param[in] publish  The Wi-Fi Aware Publish handle.
+ * @param[in] ttl              The lifetime(seconds) of publish session. 0 means forever until canceled.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
@@ -246,8 +247,8 @@ int wifi_aware_publish_set_ttl(wifi_aware_publish_h publish, unsigned short ttl)
 /**
  * @brief Set the type of the service as solicited or unsolicited.
  * @since_tizen 6.0
- * @param[in] publish
- * @param[in] publish_type
+ * @param[in] publish          The Wi-Fi Aware Publish handle
+ * @param[in] publish_type     The Publish type
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
@@ -256,8 +257,8 @@ int wifi_aware_publish_set_type(wifi_aware_publish_h publish, wifi_aware_publish
 /**
  * @brief Set the name of the service. The length should be less than or equal to 255
  * @since_tizen 6.0
- * @param[in] publish
- * @param[in] service_name UTF-8 name which identifies the service
+ * @param[in] publish          The Wi-Fi Aware Publish handle
+ * @param[in] service_name     UTF-8 name which identifies the service
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
@@ -266,20 +267,21 @@ int wifi_aware_publish_set_service_name(wifi_aware_publish_h publish, const char
 /**
  * @brief Set the specific information for the service.
  * @since_tizen 6.0
- * @param[in] publish
- * @param[in] service_specific_info
- * @param[in] len
+ * @param[in] publish                          The Wi-Fi Aware Publish handle
+ * @param[in] service_specific_info    The Sequence of values that are conveyed in the Publish message
+ * @param[in] len                                      The length of service specific information
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_publish_set_service_specific_info(wifi_aware_publish_h publish, const unsigned char *service_specific_info, size_t len);
 
 /**
- * @brief Set the match filter of the service. It is used to decide whether accepting a subscribe request or not.
+ * @brief Set the match filter of the service.
  * @since_tizen 6.0
- * @param[in] publish
- * @param[in] match_filter An ordered sequence of <length, value> pairs
- * @param[in] len
+ * @param[in] publish          The Wi-Fi Aware Publish handle
+ * @param[in] match_filter     An ordered sequence of <length, value> pairs
+ * @param[in] len                      The whole length of match_filter
+ * @remark The match filter is used to decide whether accepting a subscribe request or not.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
@@ -288,8 +290,9 @@ int wifi_aware_publish_set_match_filter(wifi_aware_publish_h publish, const unsi
 /**
  * @brief Set whether the ranging function is supported or not.
  * @since_tizen 6.0
- * @param[in] publish
- * @param[in] enable
+ * @param[in] publish  The Wi-Fi Aware Publish handle
+ * @param[in] enable   @c ture if ranging is enabled,
+ *                                             otherwise @c false if ranging is disabled.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
@@ -300,72 +303,75 @@ int wifi_aware_publish_enable_ranging(wifi_aware_publish_h publish, bool enable)
 // subscribe_config
 
 /**
- * @brief
+ * @brief Sets TTL(Time To Live) for Subscribe session.
  * @since_tizen 6.0
- * @param[in] subscribe
- * @param[in] ttl
+ * @param[in] subscribe        The Wi-Fi Aware Subscribe handle
+ * @param[in] ttl              The lifetime(seconds) of subscribe session.\n
+ *                                             0 means forever until wifi_aware_service_discovered_cb.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_subscribe_set_ttl(wifi_aware_subscribe_h subscribe, unsigned short ttl);
 
 /**
- * @brief
+ * @brief Sets the type of the service as passive or active.
  * @since_tizen 6.0
- * @param[in] subscribe
- * @param[in] subscribe_type
+ * @param[in] subscribe                        The Wi-Fi Aware Subscribe handle
+ * @param[in] subscribe_type   The Subscribe type
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_subscribe_set_type(wifi_aware_subscribe_h subscribe, wifi_aware_subscribe_type_e subscribe_type);
 
 /**
- * @brief Set the name of the service. The length should be less than or equal to 255
+ * @brief Set the name of the service. 
  * @since_tizen 6.0
- * @param[in] subscribe
- * @param[in] service_name UTF-8 name which identifies the service
+ * @param[in] subscribe                The Wi-Fi Aware Subscribe handle
+ * @param[in] service_name     UTF-8 name which identifies the service
+ * @remark     The length should be less than or equal to 255
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_subscribe_set_service_name(wifi_aware_subscribe_h subscribe, const char *service_name);
 
 /**
- * @brief
+ * @brief Sets the specific information for the service.
  * @since_tizen 6.0
- * @param[in] subscribe
- * @param[in] service_specific_info
- * @param[in] len
+ * @param[in] subscribe                                The Wi-Fi Aware Subscribe handle
+ * @param[in] service_specific_info    The Sequence of values that are conveyed in the Subscribe message
+ * @param[in] len                                      The length of service specific information
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_subscribe_set_service_specific_info(wifi_aware_subscribe_h subscribe, const unsigned char *service_specific_info, size_t len);
 
 /**
- * @brief
+ * @brief Sets the match filter of the service.
  * @since_tizen 6.0
- * @param[in] subscribe
- * @param[in] match_filter An ordered sequence of <length, value> pairs
- * @param[in] len
+ * @param[in] subscribe                The Wi-Fi Aware Subscribe handle
+ * @param[in] match_filter     An ordered sequence of <length, value> pairs
+ * @param[in] len                      The whole length of match_filter
+ * @remark The match filter is used to decide whether accepting a subscribe request or not.
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_subscribe_set_match_filter(wifi_aware_subscribe_h subscribe, const unsigned char *match_filter, size_t len);
 
 /**
- * @brief
+ * @brief Sets the maximum distance between the found services
  * @since_tizen 6.0
- * @param[in] subscribe
- * @param[in] distance
+ * @param[in] subscribe        The Wi-Fi Aware Subscribe handle
+ * @param[in] distance The max distance between found services
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_subscribe_set_max_distance(wifi_aware_subscribe_h subscribe, int distance);
 
 /**
- * @brief
+ * @brief Sets the minimum distance between the found services
  * @since_tizen 6.0
- * @param[in] subscribe
- * @param[in] distance
+ * @param[in] subscribe        The Wi-Fi Aware Subscribe handle
+ * @param[in] distance The min distance between found services
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
@@ -373,30 +379,30 @@ int wifi_aware_subscribe_set_min_distance(wifi_aware_subscribe_h subscribe, int
 
 
 /**
- * @brief
+ * @brief Called when Wi-Fi Aware is enabled.
  * @since_tizen 6.0
- * @param[in] error
- * @param[in] user_data
+ * @param[in] error            The error code
+ * @param[in] user_data        The user data passed from the request function
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 typedef void(*wifi_aware_enabled_cb)(wifi_aware_error_e error, void *user_data);
 
 /**
- * @brief Enable Wi-Fi Aware functions.
+ * @brief Enables Wi-Fi Aware functions.
  *        If Wi-Fi Aware is already enabled, the callback to return success is immediately invoked.
  * @remarks If the enable request is sucessfully done, the application can get the MAC address.
  *             TODO: Does an application need to know MAC address (NMI)?
  * @since_tizen 6.0
- * @param[in] callback The result of enable request is asynchrously delivered
- * @param[in] user_data User data
+ * @param[in] callback The result of enable request is asynchrously delivered
+ * @param[in] user_data        The user data passed to the callback function
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_enable(wifi_aware_enabled_cb callback, void *user_data);
 
 /**
- * @brief Disable Wi-Fi Aware functions.
+ * @brief Disables Wi-Fi Aware functions.
  * @since_tizen 6.0
  * @return 0 on success, otherwise a negative error value
  * @retval #WIFI_AWARE_ERROR_NONE
@@ -404,40 +410,40 @@ int wifi_aware_enable(wifi_aware_enabled_cb callback, void *user_data);
 int wifi_aware_disable();
 
 /**
- * @brief
+ * @brief Creates the Wi-Fi Aware Session.
  * @since_tizen 6.0
- * @param[in] session_type
- * @param[in] session
+ * @param[in] session_type     The type of session
+ * @param[out] session         The Wi-Fi Aware Session handle that is newly created on success
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_session_create(wifi_aware_session_type_e session_type, wifi_aware_session_h *session);
 
 /**
- * @brief
+ * @brief Destroies the Wi-Fi Aware Session.
  * @since_tizen 6.0
- * @param[in] session
+ * @param[in] session  The Wi-Fi Aware Session handle
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_session_destroy(wifi_aware_session_h session);
 
 /**
- * @brief Callback to notify that the Wi-Fi Aware Session has been lost.
+ * @brief Called when the Wi-Fi Aware Session has been lost.
  * @since_tizen 6.0
- * @param[in] session
- * @param[in] reason
- * @param[in] user_data
+ * @param[in] session  The Wi-Fi Aware Session handle
+ * @param[in] reason   The reason of termination
+ * @param[in] user_data        The user data passed from request function
  */
 typedef void(*wifi_aware_session_terminated_cb)(wifi_aware_session_h session,
                wifi_aware_termination_reason_e reason, void *user_data);
 
 /**
- * @brief
+ * @brief Registers a callback function to notify session is terminated.
  * @since_tizen 6.0
- * @param[in] session
- * @param[in] callback
- * @param[in] user_data
+ * @param[in] session  The Wi-Fi Aware Session
+ * @param[in] callback The callback function to register
+ * @param[in] user_data        The user data to be passed to the callback function
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
@@ -445,20 +451,20 @@ int wifi_aware_session_set_terminated_cb(wifi_aware_session_h session,
                wifi_aware_session_terminated_cb callback, void *user_data);
 
 /**
- * @brief
+ * @brief Unregisters the terminated callback function.
  * @since_tizen 6.0
- * @param[in] session
+ * @param[in] session  The Wi-Fi Aware Session
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  */
 int wifi_aware_session_unset_terminated_cb(wifi_aware_session_h session);
 
 /**
- * @brief This callback delivers the result of a Publish request.
+ * @brief Called when publish request is finished.
  * @since_tizen 6.0
- * @param[in] session
- * @param[in] error
- * @param[in] user_data
+ * @param[in] session  The Wi-Fi Aware Session handle
+ * @param[in] error            The error code
+ * @param[in] user_data        The user data passed from request function
  * @return     0 on success, otherwise a negative error value
  * @retval     #WIFI_AWARE_ERROR_NONE
  * @see wifi_aware_session_publish()
@@ -468,7 +474,7 @@ typedef void(*wifi_aware_published_cb)(wifi_aware_session_h session,
                wifi_aware_error_e error, void *user_data);
 
 /**
- * @brief Publish a Wi-Fi Aware service so that neighboring devices can find it.
+ * @brief Publishes a Wi-Fi Aware service so that neighboring devices can find it.
  * @since_tizen 6.0
  * @param[in] sesssion
  * @param[in] publish