Reinforce API documents

Change-Id: I39f9166986b5d148e8488fd85e8b68fc78217ab0
Signed-off-by: Wootak Jung <wootak.jung@samsung.com>

diff --git a/doc/bluetooth_doc.h b/doc/bluetooth_doc.h
index 59db437f8e66b7a2d0c199e25d2d8fe50f4f6590..21c00af90293683030bbc44c6df02d0bd9ba5419 100644 (file)
--- a/doc/bluetooth_doc.h
+++ b/doc/bluetooth_doc.h
@@ -59,12 +59,10 @@
  *  \#include <bluetooth.h>
  *
  * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE_OVERVIEW Overview
- * This set of function is used to control a bluetooth adapter.
- * You can also control visibility of the device, its appearance for others (adapter name).
- * In addition, this api is used to discover neighboring bluetooth devices.
- * This process is asynchronous, so it is up to you to build and hold list of devices in the neighborhood
- * - the api does not provide this list.
- * Before starting a device discovery, you can find a device from the connected devices.
+ * The Bluetooth Adapter APIs allow you to retrieve and set the current state, address, and name of your local Bluetooth adapter.
+ * Additionally, it enables checking the visibility mode of the adapter, starting/stopping device discovery,
+ * retrieving information about connected devices, determining whether specific services are being utilized,
+ * registering callbacks for various types of updates, and unregistering those callbacks when no longer needed.
  * This functionality is implemented by foreach loop.
  *
  * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE_FEATURE Related Features
@@ -165,7 +163,10 @@
  *  \#include <bluetooth.h>
  *
  * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE_OVERVIEW Overview
- * Bluetooth stack architecture has been changed. Thus, GATT APIs defined in Tizen 2.3 are deprecated and new GATT client APIs are defined.
+ * The Bluetooth Adapter LE APIs facilitate operations involving Low Energy (LE) communication.
+ * They offer functions to check for active LE scans, initiate and stop LE scans, extract meaningful information from scan results,
+ * create and manage advertisers for broadcast purposes, add essential elements to advertising data, configure advertising settings, clear advertising data,
+ * start new advertising sessions, adjust advertising connectivity preferences, define LE scan modes, establish and remove scan filters, and register/unregister these filters.
  *
  * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE_FEATURE Related Features
  * This API is related with the following features:\n
@@ -191,7 +192,9 @@
  *  \#include <bluetooth.h>
  *
  * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_50_MODULE_OVERVIEW Overview
- * Bluetooth LE API provides functions for bluetooth 5.0 functionality such as 2M Phy and Coded Phy
+ * The Bluetooth Adapter LE APIs extend their capabilities to include features related to LE 2M PHY and LE Coded PHY support checks.
+ * These APIs assist developers in verifying whether the LE 2M PHY and LE Coded PHY functionalities are available within the platform they're working on.
+ * This allows for improved understanding of the underlying hardware's compatibility with advanced LE technologies.
  *
  * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_50_MODULE_FEATURE Related Features
  * This API is related with the following features:\n
@@ -217,7 +220,13 @@
  *  \#include <bluetooth.h>
  *
  * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_ADV_EXT_MODULE_OVERVIEW Overview
- * Bluetooth LE API provides functions for bluetooth extended advertising functionality such as setting Primary and Secondary Phy
+ * The Bluetooth Adapter LE APIs provide several functions to enhance the LE experience.
+ * These include starting a new LE scan session, adjusting the LE scan role, selecting the preferred LE scan physical layer,
+ * enabling or disabling LE advertising legacy mode, specifying the primary and secondary LE advertising physical layers,
+ * confirming LE Extended Advertising and Extended Scan support availability, obtaining the maximum allowed advertising data length,
+ * accessing primary and secondary LE physical layer data from extended scan results, retrieving advertising SID values,
+ * periodic advertising intervals, determining whether a scan result is considered "extended", and fetching legacy scan result information from extended scan results.
+ * These features cater to diverse needs while ensuring efficient utilization of LE resources.
  *
  * @section CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_ADV_EXT_MODULE_FEATURE Related Features
  * This API is related with the following features:\n
@@ -510,7 +519,14 @@
  *  \#include <bluetooth.h>
  *
  * @section CAPI_NETWORK_BLUETOOTH_OPP_MODULE_OVERVIEW Overview
- * OPP profile let users exchange objects between two devices.
+ * Bluetooth Object Push Profile (OPP) Client APIs supply a set of operations geared toward transferring files like images. Core elements comprise:
+ * - Initialization of Bluetooth OPP client modules
+ * - Deinitialization of Bluetooth OPP client modules
+ * - Addition of files intended for transmission
+ * - Clearing of queued files awaiting transfer
+ * - Asynchronous dispatch of file pushes to remote devices, coupled with event callbacks signaling response reception, progress updates, and task conclusion
+ * - Cancellation of active push requests, also implemented asynchronously
+ * Through this framework, developers can effortlessly orchestrate Bluetooth-based object transfers involving OPP clients.
  *
  */
 
@@ -523,7 +539,14 @@
  *  \#include <bluetooth.h>
  *
  * @section CAPI_NETWORK_BLUETOOTH_OPP_SERVER_MODULE_OVERVIEW Overview
- * This is OPP server APIs.
+ * Bluetooth Object Push Profile (OPP) Server APIs deliver a series of constructs focused on receiving files such as photographs. Fundamental building blocks consist of:
+ * - Initialization of Bluetooth OPP servers prompted by connection request callbacks
+ * - Deinitialization of Bluetooth OPP servers
+ * - Acceptance of push requests from remote devices, accompanied by progress update and completion notification callbacks, alongside optional name assignments and user data inputs, yielding unique transfer identifiers
+ * - Rejection of incoming push requests
+ * - Cancellation of ongoing file transfers, referencing assigned transfer IDs
+ * - Configuration of desired storage destinations for received files
+ * These streamlined tools enable straightforward implementation of Bluetooth-powered OPP server functionality.
  *
  * @section CAPI_NETWORK_BLUETOOTH_OPP_SERVER_MODULE_FEATURE Related Features
  * This API is related with the following features:\n
@@ -651,6 +674,12 @@
  * @section CAPI_NETWORK_BLUETOOTH_HID_MODULE_OVERVIEW Overview
  * In HID Profile, there are two roles - @a Host and @a Device.
  * The @a Host is a device that uses or requests the services of a HID. The @a Device is a device that provides the service of human data input and output to and from th
+ * Bluetooth Human Interface Device (HID) APIs furnish a collection of functionalities tailored towards linking with Bluetooth HID peripherals, such as keyboards and mouse. Primary offerings entail:
+ * - Initialization of Bluetooth HID Host, accompanied by optional callbacks for tracking connection state changes
+ * - Deinitialization of Bluetooth HID Host
+ * - Connection setup with remote devices featuring HID services, performed asynchronously
+ * - Disconnection of remote devices equipped with HID services, likewise conducted asynchronously
+ * By harnessing these capabilities, developers gain access to simplified pathways for interfacing with Bluetooth HID accessories.
  *
  * @section CAPI_NETWORK_BLUETOOTH_HID_MODULE_FEATURE Related Features
  * This API is related with the following features:\n
@@ -876,8 +905,11 @@
  *  \#include <bluetooth.h>
  *
  * @section CAPI_NETWORK_BLUETOOTH_HDP_MODULE_OVERVIEW Overview
- * The @a Source is a transmitter of application data that is to be transferred to a @a Sink. The @a Sink is a receiver of application data delivered from a @a Source.
- * This API supports the @a Sink role in HDP spec.
+ * Bluetooth Health Device Profile (HDP) APIs offer a suite of utilities designed for handling connections to medical equipment and facilitating data exchange. Highlights include:
+ * - Establishing links to remote devices operating as sources, utilizing remote addresses and app IDs, in an asynchronous manner
+ * - Disconnecting remote devices, employing remote addresses and channel numbers, again asynchronously
+ * - Transferring data packets via specified channels and defined payload sizes
+ * These streamlined tools promote smooth interoperability between Bluetooth-enabled healthcare devices.
  *
  * @section CAPI_NETWORK_BLUETOOTH_HDP_MODULE_FEATURE Related Features
  * This API is related with the following features:\n

diff --git a/include/bluetooth.h b/include/bluetooth.h
index aa74ad22c102d8333fe12d83be35c386a90d95af..bf2edf18f6ef5242eb6480bb22169f365f6b05f6 100644 (file)
--- a/include/bluetooth.h
+++ b/include/bluetooth.h
@@ -119,6 +119,8 @@ int bt_adapter_get_state(bt_adapter_state_e *adapter_state);
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE
  * @brief Gets the address of local Bluetooth adapter.
+ * @details This function obtains the address of the local Bluetooth adapter and assigns it to the @a local_address output parameter.
+ *
  * @since_tizen 2.3
  *
  * @remarks The @a local_address must be released with free() by you.
@@ -326,6 +328,9 @@ int bt_device_get_service_mask_from_uuid_list(char **uuids,
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE
  * @brief Retrieves the device information of all bonded devices.
+ * @details This function iterates through each bonded device and calls the supplied @a callback function,
+ *          passing along the device information for each iteration.
+ *          The @a user_data argument allows for custom data to be passed from the caller to the callback function.
  * @since_tizen 2.3
  *
  * @param[in] callback The callback function to invoke
@@ -489,6 +494,8 @@ int bt_adapter_unset_name_changed_cb(void);
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_MODULE
  * @brief Registers a callback function to be invoked when the visibility mode changes.
+ * @details This function registers a callback function that gets called whenever the visibility mode of the local Bluetooth adapter changes.
+ *          The registered callback function receives two arguments the new visibility mode and the user data passed from the @a bt_adapter_set_visibility_mode_changed_cb() function.
  * @since_tizen 2.3
  *
  * @param[in] callback The callback function to register
@@ -1342,6 +1349,8 @@ int bt_adapter_le_add_advertising_service_data(bt_advertiser_h advertiser,
  * @ingroup CAPI_NETWORK_BLUETOOTH_ADAPTER_LE_MODULE
  * @brief Sets the external appearance of this device to advertise or scan response data.
  *        Please refer to the adopted Bluetooth specification for the the appearance.
+ * @details This function sets the external appearance of the device for purposes of advertising or responding to scans.
+ *          The appearance value corresponds to the appropriate Bluetooth specification.
  * @since_tizen 2.3.1
  *
  * @param[in] advertiser The handle of advertiser
@@ -2137,6 +2146,8 @@ int bt_socket_listen_and_accept_rfcomm(int socket_fd, int max_pending_connection
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_SOCKET_MODULE
  * @brief Connects to a specific RFCOMM based service on a remote Bluetooth device UUID, asynchronously.
+ * @details This function facilitates the creation of an asynchronous connection between the local host
+ *          and a designated RFCOMM-based service hosted by a remote Bluetooth device, identified uniquely by its UUID.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/bluetooth
@@ -2620,6 +2631,7 @@ int bt_hid_host_deinitialize(void);
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_HID_HOST_MODULE
  * @brief Connects the remote device with the HID (Human Interface Device) service, asynchronously.
+ * @details This function establishes an asynchronous connection to a remote device providing the Human Interface Device (HID) service.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/bluetooth
@@ -2858,6 +2870,8 @@ int bt_hid_device_unset_data_received_cb(void);
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_HID_DEVICE_MODULE
  * @brief Responds to reports from the HID Host.
+ * @details This function facilitates responding to reports generated by the HID Host.
+ *          Through this approach, the application can deliver personalized data back to the host.
  * @since_tizen 3.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/bluetooth
@@ -3069,6 +3083,8 @@ int bt_avrcp_target_notify_equalizer_state(bt_avrcp_equalizer_state_e state);
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_AVRCP_TARGET_MODULE
  * @brief  Notifies the repeat mode to the remote device.
+ * @details This function informs the remote device regarding the selected repeat mode.
+ *          AVRCP Target uses this mechanism to communicate playback settings to the remote player.
  * @since_tizen 2.4
  * @privlevel public
  * @privilege %http://tizen.org/privilege/bluetooth
@@ -3092,6 +3108,8 @@ int bt_avrcp_target_notify_repeat_mode(bt_avrcp_repeat_mode_e mode);
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_AVRCP_TARGET_MODULE
  * @brief  Notifies the shuffle mode to the remote device.
+ * @details This function transmits the designated shuffle mode to the remote device.
+ *          AVRCP Target leverages this functionality to convey shuffling preferences to the remote music player.
  * @since_tizen 2.4
  * @privlevel public
  * @privilege %http://tizen.org/privilege/bluetooth
@@ -3161,6 +3179,8 @@ int bt_avrcp_target_notify_player_state(bt_avrcp_player_state_e state);
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_AVRCP_TARGET_MODULE
  * @brief  Notifies the current position of song to the remote device.
+ * @details This function conveys the current playing position of the track to the remote device.
+ *          AVRCP Target relies on this capability to update the playback progress on the remote music player.
  * @since_tizen 2.4
  * @privlevel public
  * @privilege %http://tizen.org/privilege/bluetooth
@@ -3184,6 +3204,8 @@ int bt_avrcp_target_notify_position(unsigned int position);
 /**
  * @ingroup CAPI_NETWORK_BLUETOOTH_AVRCP_TARGET_MODULE
  * @brief  Notifies the track to the remote device.
+ * @details This function notifies the remote device about the currently playing track.
+ *          AVRCP Target makes use of this feature to share metadata related to the active tune with the remote music player.
  * @since_tizen 2.4
  * @privlevel public
  * @privilege %http://tizen.org/privilege/bluetooth