Fixed doxygen documentation issues in wifi-direct.h

Change-Id: Iadda688708081fede3cf4ba3b3a904cfe312d71c
Signed-off-by: Nishant Chaprana <n.chaprana@samsung.com>

diff --git a/include/wifi-direct.h b/include/wifi-direct.h
index 9044919..fde8cea 100755 (executable)
--- a/include/wifi-direct.h
+++ b/include/wifi-direct.h
@@ -598,6 +598,7 @@ typedef void (*wifi_direct_discovery_state_chagned_cb) (int error_code,
  *          #WIFI_DIRECT_ERROR_OPERATION_FAILED
  *          #WIFI_DIRECT_ERROR_NOT_PERMITTED
  * @since_tizen 2.3
+ * @remarks The @a mac_address can be used only in the callback. To use outside, make a copy.
  * @param[in] error_code       The error code
  * @param[in] discovery_state  The discovery state
  * @param[in] mac_address      The MAC address of found peer
@@ -647,6 +648,7 @@ typedef void (*wifi_direct_device_state_changed_cb) (int error_code,
  *          #WIFI_DIRECT_ERROR_NOT_PERMITTED
  *          #WIFI_DIRECT_ERROR_CONNECTION_FAILED
  * @since_tizen 2.3
+ * @remarks The @a mac_address can be used only in the callback. To use outside, make a copy.
  * @param[in] error_code        The error code
  * @param[in] connection_state  The connection state
  * @param[in] mac_address       The MAC address of the connection peer
@@ -669,11 +671,11 @@ typedef void (*wifi_direct_connection_state_changed_cb) (int error_code,
 
 /**
  * @brief Called when the state of connection is changed.
- * @since_tizen 5.0
  * @details The following error codes can be delivered:\n
  *     #WIFI_DIRECT_ERROR_NONE\n
  *     #WIFI_DIRECT_ERROR_OPERATION_FAILED\n
  *     #WIFI_DIRECT_ERROR_NOT_PERMITTED
+ * @since_tizen 5.0
  * @param[in] error_code  The error code
  * @param[in] connection_state  The connection state
  * @param[in] data_s The structure for peer data
@@ -698,6 +700,9 @@ typedef void (*wifi_direct_peer_info_connection_state_changed_cb)(wifi_direct_er
  *          #WIFI_DIRECT_ERROR_OPERATION_FAILED
  *          #WIFI_DIRECT_ERROR_NOT_PERMITTED
  * @since_tizen 2.3
+ * @remarks The @a mac_address can be used only in the callback. To use outside, make a copy.
+ *          The @a ip_address can be used only in the callback. To use outside, make a copy.
+ *          The @a interface_address can be used only in the callback. To use outside, make a copy.
  * @param[in] mac_address        The MAC address of connection peer
  * @param[in] ip_address         The IP address of connection peer
  * @param[in] interface_address  The interface address of connection peer
@@ -720,6 +725,7 @@ typedef void (*wifi_direct_client_ip_address_assigned_cb) (const char *mac_addre
  *          #WIFI_DIRECT_ERROR_OPERATION_FAILED
  *          #WIFI_DIRECT_ERROR_NOT_PERMITTED
  * @since_tizen 2.3
+ * @remarks The @a mac_address can be used only in the callback. To use outside, make a copy.
  * @param[in] error_code     The error code
  * @param[in] service_state  The service discovery state
  * @param[in] service_type   Specifies the types of service
@@ -847,7 +853,7 @@ int wifi_direct_deinitialize(void);
 
 
 /**
- * @brief Registers the callback called when the state of device is changed.
+ * @brief Sets the callback called when the state of device is changed.
  * @since_tizen 2.3
  * @param[in] cb         The callback function to invoke
  * @param[in] user_data  The user data to be passed to the callback function
@@ -921,7 +927,7 @@ int wifi_direct_set_device_state_changed_cb(wifi_direct_device_state_changed_cb
 
 
 /**
- * @brief Unregisters the callback called when the state of device is changed.
+ * @brief Unsets the callback called when the state of device is changed.
  * @since_tizen 2.3
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -965,7 +971,7 @@ int wifi_direct_unset_device_state_changed_cb(void);
 
 
 /**
- * @brief Registers the callback called when the state of discovery is changed.
+ * @brief Sets the callback called when the state of discovery is changed.
  * @since_tizen 2.3
  * @param[in] cb         The callback function to invoke
  * @param[in] user_data  The user data to be passed to the callback function
@@ -1046,7 +1052,7 @@ int wifi_direct_set_discovery_state_changed_cb(wifi_direct_discovery_state_chagn
 
 
 /**
- * @brief Unregisters the callback called when the state of discovery is changed.
+ * @brief Unsets the callback called when the state of discovery is changed.
  * @since_tizen 2.3
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -1092,7 +1098,7 @@ int wifi_direct_unset_discovery_state_changed_cb(void);
 
 
 /**
- * @brief Registers the callback called when the peer is found.
+ * @brief Sets the callback called when the peer is found.
  * @since_tizen 2.3
  * @param[in] cb         The callback function to invoke
  * @param[in] user_data  The user data to be passed to the callback function
@@ -1161,7 +1167,7 @@ int wifi_direct_set_peer_found_cb(wifi_direct_peer_found_cb cb, void* user_data)
 
 
 /**
- * @brief Unregisters the callback called when the peer is found.
+ * @brief Unsets the callback called when the peer is found.
  * @since_tizen 2.3
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -1205,7 +1211,7 @@ int wifi_direct_unset_peer_found_cb(void);
 
 
 /**
- * @brief Registers the callback called when the state of connection is changed.
+ * @brief Sets the callback called when the state of connection is changed.
  * @since_tizen 2.3
  * @param[in] cb         The callback function to invoke
  * @param[in] user_data  The user data to be passed to the callback function
@@ -1350,7 +1356,7 @@ int wifi_direct_set_connection_state_changed_cb(wifi_direct_connection_state_cha
 
 
 /**
- * @brief Unregisters the callback called when the state of connection is changed.
+ * @brief Unsets the callback called when the state of connection is changed.
  * @since_tizen 2.3
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -1426,7 +1432,7 @@ int wifi_direct_unset_peer_info_connection_state_changed_cb(void);
 
 
 /**
- * @brief Registers the callback called when the IP address of the client is assigned
+ * @brief Sets the callback called when the IP address of the client is assigned
  *        if your device is the group owner.
  * @since_tizen 2.3
  * @param[in] cb         The callback function to invoke
@@ -1491,7 +1497,7 @@ int wifi_direct_set_client_ip_address_assigned_cb(wifi_direct_client_ip_address_
 
 
 /**
- * @brief Unregisters the callback called when the IP address of the client is assigned
+ * @brief Unsets the callback called when the IP address of the client is assigned
  *        if your device is the group owner.
  * @since_tizen 2.3
  * @return @c 0 on success,
@@ -1536,7 +1542,7 @@ int wifi_direct_unset_client_ip_address_assigned_cb(void);
 
 
 /**
- * @brief Registers the callback called when the state of the service discovery is changed.
+ * @brief Sets the callback called when the state of the service discovery is changed.
  * @since_tizen 2.3
  * @param[in] cb         The callback function to invoke
  * @param[in] user_data  The user data to be passed to the callback function
@@ -1629,7 +1635,7 @@ int wifi_direct_set_service_state_changed_cb(wifi_direct_service_state_changed_c
 
 
 /**
- * @brief Unregisters the callback called when the state of the service discovery is changed.
+ * @brief Unsets the callback called when the state of the service discovery is changed.
  * @since_tizen 2.3
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -1673,7 +1679,7 @@ int wifi_direct_unset_service_state_changed_cb(void);
 
 
 /**
- * @brief Registers the callback called when the state of Wi-Fi Direct is changed.
+ * @brief Sets the callback called when the state of Wi-Fi Direct is changed.
  * @since_tizen 3.0
  * @param[in] cb         The callback function to invoke
  * @param[in] user_data  The user data to be passed to the callback function
@@ -1749,7 +1755,7 @@ int wifi_direct_set_state_changed_cb(wifi_direct_state_changed_cb cb, void *user
 
 
 /**
- * @brief Unregisters the callback called when the state of Wi-Fi Direct is changed.
+ * @brief Unsets the callback called when the state of Wi-Fi Direct is changed.
  * @since_tizen 3.0
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -2015,15 +2021,15 @@ int wifi_direct_start_discovery(bool listen_only, int timeout);
 
 /**
  * @brief Starts discovery to find all P2P capable devices with specified channel, asynchronously.
- * @details If you call this function with @a channel as @c WIFI_DIRECT_DISCOVERY_FULL_SCAN
+ * @details If you call this function with @a channel as @c #WIFI_DIRECT_DISCOVERY_FULL_SCAN
  *          it works same as wifi_direct_start_discovery() API.
- *          If application developers call this function with @a channel as @c WIFI_DIRECT_DISCOVERY_SOCIAL_CHANNEL,
+ *          If application developers call this function with @a channel as @c #WIFI_DIRECT_DISCOVERY_SOCIAL_CHANNEL,
  *          then will search only the devices on the social channels(channel 1 or 6 or 11).
- *          If application developers call this function with @a type as @c WIFI_DIRECT_DISCOVERY_CHANNEL1,
+ *          If application developers call this function with @a channel as @c #WIFI_DIRECT_DISCOVERY_CHANNEL1,
  *          then will search only the devices on the channel 1.
- *          If application developers call this function with @a type as @c WIFI_DIRECT_DISCOVERY_CHANNEL6,
+ *          If application developers call this function with @a channel as @c #WIFI_DIRECT_DISCOVERY_CHANNEL6,
  *          then will search only the devices on the channel 6.
- *          If application developers call this function with @a type as @c WIFI_DIRECT_DISCOVERY_CHANNEL11,
+ *          If application developers call this function with @a channel as @c #WIFI_DIRECT_DISCOVERY_CHANNEL11,
  *          then will search only the devices on the channel 11.
  * @since_tizen 2.3
  * @privlevel public
@@ -2244,7 +2250,7 @@ int wifi_direct_start_discovery_specific_freq(bool listen_only, int timeout, int
 /**
  * @brief Cancels discovery process, asynchronously.
  * @details This function stops all discovery processes started with
- *          wifi_direct_start_discovery... functions.
+ *          wifi_direct_start_discovery() functions.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
@@ -2454,7 +2460,7 @@ int wifi_direct_foreach_discovered_peers(wifi_direct_discovered_peer_cb callback
 
 /**
  * @brief Connects to a specified peer, asynchronously.
- * @details This API connects to specified peer by automatically determining
+ * @details This function connects to specified peer by automatically determining
  *          whether to perform group formation, join an existing group, invite, re-invoke a group.
  *          The decision is based on the current state of the peers (i.e. GO, STA, not connected)
  *          and the availability of persistent data.
@@ -2606,6 +2612,7 @@ int wifi_direct_connect(char *mac_address);
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #WIFI_DIRECT_ERROR_NONE                  Successful
+ * @retval #WIFI_DIRECT_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #WIFI_DIRECT_ERROR_OPERATION_FAILED      Operation failed
  * @retval #WIFI_DIRECT_ERROR_COMMUNICATION_FAILED  Communication failed
  * @retval #WIFI_DIRECT_ERROR_PERMISSION_DENIED     Permission denied
@@ -3027,7 +3034,7 @@ int wifi_direct_foreach_connected_peers(wifi_direct_connected_peer_cb callback,
 
 /**
  * @brief Creates a Wi-Fi Direct Group, asynchronously.
- * @details This API sets up device as the Group Owner and waits for clients to connect.
+ * @details This function sets up device as the Group Owner and waits for clients to connect.
  *          In addition, a soft AP will be created, the WPS registrar and the DHCP server will be started.
  * @since_tizen 2.3
  * @privlevel public
@@ -3101,9 +3108,9 @@ int wifi_direct_create_group(void);
 
 /**
  * @brief Creates a Wi-Fi Direct Group, asynchronously with given SSID name.
- * @since_tizen 5.0
  * @details This function sets up device as the Group Owner and waits for clients to connect.
  * In addition, a soft AP will be created, the WPS registrar and the DHCP server will be started.
+ * @since_tizen 5.0
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
  * @param[in] ssid  Referred to as a network name, it is a name that identifies a wireless network
@@ -3127,8 +3134,8 @@ int wifi_direct_create_group_with_ssid(const char *ssid);
 
 /**
  * @brief Destorys the Wi-Fi Direct Group, asynchronously.
- * @details This API destroys the Wi-Fi Direct Group owned by a local device.
- *          If creating a Group is in progress, this API cancels that creating.
+ * @details This function destroys the Wi-Fi Direct Group owned by a local device.
+ *          If creating a Group is in progress, this function cancels that creating.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
@@ -3499,7 +3506,7 @@ int wifi_direct_get_device_name(char** device_name);
 
 
 /**
- * @brief Gets SSID(Service Set Identifier) of a local device.
+ * @brief Gets SSID (Service Set Identifier) of a local device.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
@@ -4669,7 +4676,6 @@ int wifi_direct_get_secondary_device_type(wifi_direct_secondary_device_type_e* t
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #WIFI_DIRECT_ERROR_NONE                  Successful
- * @retval #WIFI_DIRECT_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #WIFI_DIRECT_ERROR_OPERATION_FAILED      Operation failed
  * @retval #WIFI_DIRECT_ERROR_COMMUNICATION_FAILED  Communication failed
  * @retval #WIFI_DIRECT_ERROR_PERMISSION_DENIED     Permission denied
@@ -5063,7 +5069,7 @@ int wifi_direct_get_wps_pin(char **pin);
  * @since_tizen 2.3
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
- * @param[out] wps_mode  Supported wps mode for local device
+ * @param[out] wps_mode  Supported WPS mode for local device
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #WIFI_DIRECT_ERROR_NONE                  Successful
@@ -5134,7 +5140,7 @@ int wifi_direct_get_supported_wps_mode(int *wps_mode);
 
 
 /**
- * @brief Called when you get the supported WPS(Wi-Fi Protected Setup) type repeatedly.
+ * @brief Called when you get the supported WPS (Wi-Fi Protected Setup) type repeatedly.
  * @since_tizen 2.3
  * @param[in] type       The type of WPS
  * @param[in] user_data  The user data passed from the request function
@@ -5776,8 +5782,8 @@ int wifi_direct_get_max_clients(int *max);
  * @since_tizen 2.4
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
- * @param passphrase new wpa password to set. Application must set the new password before.
- * @remarks a peer can connect to this group as Wi-Fi Infrastructured mode with a passphrase.
+ * @remarks A peer can connect to this group as Wi-Fi Infrastructured mode with a passphrase.
+ * @param[in] passphrase new wpa password to set. Application must set the new password before.
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #WIFI_DIRECT_ERROR_NONE                  Successful
@@ -5974,7 +5980,7 @@ int wifi_direct_get_operating_channel(int *channel);
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
  * @param[in] mode  Describes the mode of connection. In case of TRUE \n
- *                     auto-connection will be taken care by framework
+ *                      auto-connection will be taken care by framework
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #WIFI_DIRECT_ERROR_NONE               Successful
@@ -6367,6 +6373,8 @@ int wifi_direct_is_persistent_group_enabled(bool *enabled);
 /**
  * @brief Called when you get the persistent groups repeatedly.
  * @since_tizen 2.3
+ * @remarks The @a mac_address can be used only in the callback. To use outside, make a copy.
+ *          The @a ssid can be used only in the callback. To use outside, make a copy.
  * @param[in] mac_address  The MAC address of the persistent group owner
  * @param[in] ssid         The SSID (Service Set Identifier) of the persistent group owner
  * @param[in] user_data    The user data passed from the request function
@@ -6530,12 +6538,12 @@ int wifi_direct_remove_persistent_group(char *mac_address, const char *ssid);
 
 
 /**
- * @brief WiFi Direct Service Discovery will be started.
+ * @brief Starts wifi direct service discovery.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
  * @param[in] mac_address   The MAC address of servicing device. A broadcast \n
- *                              will be sent when MAC is SET to ZERO
+ *                               will be sent when MAC is SET to ZERO
  * @param[in] service_type  Describes the type of service
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -6650,12 +6658,12 @@ int wifi_direct_start_service_discovery(char *mac_address, wifi_direct_service_t
 
 
 /**
- * @brief A service started for Wi-Fi Direct Service Discovery will be stopped.
+ * @brief Cancels an ongoing wifi direct service discovery.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
  * @param[in] mac_address  The MAC address of servicing device. A broadcast \n
- *                            will be sent when MAC is SET to ZERO
+ *                             will be sent when MAC is SET to ZERO
  * @param[in] service_type Describes the type of service
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -7084,7 +7092,6 @@ int wifi_direct_get_peer_info(char *mac_address, wifi_direct_discovered_peer_inf
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #WIFI_DIRECT_ERROR_NONE                  Successful
- * @retval #WIFI_DIRECT_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #WIFI_DIRECT_ERROR_OPERATION_FAILED      Operation failed
  * @retval #WIFI_DIRECT_ERROR_COMMUNICATION_FAILED  Communication failed
  * @retval #WIFI_DIRECT_ERROR_PERMISSION_DENIED     Permission denied
@@ -7140,14 +7147,13 @@ int wifi_direct_init_display(void);
 
 
 /**
- * @brief This API shall disable Wi-Fi Display functionality & disable the support of WFD Information Element (IE).
+ * @brief Disables Wi-Fi Display functionality & disables the support of WFD Information Element (IE).
  * @since_tizen 2.4
  * @privlevel public
  * @privilege http://tizen.org/privilege/wifidirect
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #WIFI_DIRECT_ERROR_NONE                  Successful
- * @retval #WIFI_DIRECT_ERROR_INVALID_PARAMETER     Invalid parameter
  * @retval #WIFI_DIRECT_ERROR_OPERATION_FAILED      Operation failed
  * @retval #WIFI_DIRECT_ERROR_COMMUNICATION_FAILED  Communication failed
  * @retval #WIFI_DIRECT_ERROR_PERMISSION_DENIED     Permission denied
@@ -7840,7 +7846,7 @@ int wifi_direct_get_peer_display_throughput(char *mac_address, int *throughput);
  * @retval #WIFI_DIRECT_ERROR_RESOURCE_BUSY         Device or resource busy
  * @pre Wi-Fi Direct service must be activated by wifi_direct_activate().
  * @post wifi_direct_connection_state_changed_cb() will be invoked with
- *       WIFI_DIRECT_GROUP_DESTROYED when there's no connected Group Client
+ *       #WIFI_DIRECT_GROUP_DESTROYED when there's no connected Group Client
  *       if device is Group Owner and this feature is enabled.
  * @see wifi_direct_activate()
  * @see wifi_direct_create_group()