bluetooth: services: improve doxygen for init functions

The doxygen comments for functions responsible for
initializing GATT services did not make it clear that GATT
services are registered statically and the init functions
are just for initializing the service dependencies.

JIRA: KRKNWK-21046

Signed-off-by: Damian Krolik <damian.krolik@nordicsemi.no>

Author: Damian-Nordic

include/bluetooth/services/bms.h

@@ -101,14 +101,15 @@ struct bt_bms_init_params {
 
 /** @brief Initialize the BMS Service.
  *
- *  Initialize the BMS Service by specifying a list of supported operations.
- *  If any operation is configured as authorized, you need to provide
- *  authorize() callback.
+ *  Initializes the module with the list of supported operations.
+ *  If any operation is configured as authorized, the authorize() callback must be provided.
  *
- *  @param init_params Initialization parameters.
+ *  @note The GATT service is defined and registered statically at compile time.
+ *
+ *  @param init_params Initialization parameters. Must not be NULL.
  *
  *  @retval 0 If the operation was successful.
- *            Otherwise, a (negative) error code is returned.
+ *          Otherwise, a negative error code is returned.
  */
 int bt_bms_init(const struct bt_bms_init_params *init_params);
 

include/bluetooth/services/cgms.h

@@ -112,12 +112,14 @@ int bt_cgms_measurement_add(struct bt_cgms_measurement measurement);
 
 /** @brief Initialize Continuous Glucose Monitoring service.
  *
- * This will initialize components used in CGMS.
+ *  Initializes the module with the given initialization parameters.
  *
- *  @param[in] init_params The parameter used to initialize the corresponding
- *             values of CGMS module.
+ *  @note The GATT service is defined and registered statically at compile time.
  *
- *  @return Zero in case of success and error code in case of error.
+ *  @param[in] init_params Initialization parameters. Must not be NULL.
+ *
+ *  @retval 0 If the operation was successful.
+ *          Otherwise, a negative error code is returned.
  */
 int bt_cgms_init(struct bt_cgms_init_param *init_params);
 

include/bluetooth/services/ddfs.h

@@ -208,7 +208,7 @@ struct bt_ddfs_init_params {
 	const struct bt_ddfs_cb *cb;
 };
 
-/** @brief Function for sending Distance Measurement value.
+/** @brief Send Distance Measurement value.
  *
  *  The application calls this function after having performed a Distance Measurement.
  *  If notification has been enabled, the measurement data is encoded and sent to the client.
@@ -222,7 +222,7 @@ struct bt_ddfs_init_params {
 int bt_ddfs_distance_measurement_notify(struct bt_conn *conn,
 					const struct bt_ddfs_distance_measurement *measurement);
 
-/** @brief Function for sending Azimuth Measurement value.
+/** @brief Send Azimuth Measurement value.
  *
  *  The application calls this function after having performed an Azimuth Measurement.
  *  If notification has been enabled, the measurement data is encoded and sent to the client.
@@ -236,7 +236,7 @@ int bt_ddfs_distance_measurement_notify(struct bt_conn *conn,
 int bt_ddfs_azimuth_measurement_notify(struct bt_conn *conn,
 				       const struct bt_ddfs_azimuth_measurement *measurement);
 
-/** @brief Function for sending Elevation Measurement value.
+/** @brief Send Elevation Measurement value.
  *
  *  The application calls this function after having performed an Elevation Measurement.
  *  If notification has been enabled, the measurement data is encoded and sent to the client.
@@ -250,9 +250,13 @@ int bt_ddfs_azimuth_measurement_notify(struct bt_conn *conn,
 int bt_ddfs_elevation_measurement_notify(struct bt_conn *conn,
 					const struct bt_ddfs_elevation_measurement *measurement);
 
-/** @brief Function for initializing the Direction and Distance Finding Service.
+/** @brief Initialize the Direction and Distance Finding Service.
  *
- *  @param[in] init Initialization parameters.
+ *  Initializes the module with the given initialization parameters.
+ *
+ *  @note The GATT service is defined and registered statically at compile time.
+ *
+ *  @param[in] init Initialization parameters. Must not be NULL.
  *
  *  @retval 0 If the operation was successful.
  *          Otherwise, a negative error code is returned.

include/bluetooth/services/latency.h

@@ -63,17 +63,20 @@ struct bt_latency {
 /** @brief UUID of the Latency Characteristic. **/
 #define BT_UUID_LATENCY_CHAR BT_UUID_DECLARE_128(BT_UUID_LATENCY_CHAR_VAL)
 
-/** @brief Initialize the GATT latency service.
+/** @brief Initialize the GATT Latency Service instance.
+ *
+ *  Marks the instance as initialized and stores the given callbacks.
+ *
+ *  @note The GATT service is defined and registered statically at compile time.
  *
  *  @param[in] latency Latency service instance.
- *  @param[in] cb Callbacks.
+ *  @param[in] cb Struct containing pointers to callback functions.
+ *                Can be NULL if no callbacks are defined.
  *
  *  @retval 0 If the operation was successful.
  *            Otherwise, a negative error code is returned.
- *  @retval (-EINVAL) Special error code used when the input
- *          parameters are invalid.
- *  @retval (-EALREADY) Special error code used when the latency
- *          service has been initialed.
+ *  @retval -EINVAL Input parameters are invalid.
+ *  @retval -EALREADY Latency service has already been initialized.
  */
 int bt_latency_init(struct bt_latency *latency,
 		    const struct bt_latency_cb *cb);

include/bluetooth/services/lbs.h

@@ -52,20 +52,17 @@ struct bt_lbs_cb {
 
 /** @brief Initialize the LBS Service.
  *
- * This function registers a GATT service with two characteristics: Button
- * and LED.
- * Send notifications for the Button Characteristic to let connected peers know
- * when the button state changes.
- * Write to the LED Characteristic to change the state of the LED on the
- * board.
+ *  Initializes the module with the given callbacks, used when:
+ *  - The LED characteristic is written to by a remote device.
+ *  - The button characteristic is read by a remote device.
  *
- * @param[in] callbacks Struct containing pointers to callback functions
- *			used by the service. This pointer can be NULL
- *			if no callback functions are defined.
+ *  @note The GATT service is defined and registered statically at compile time.
  *
+ *  @param[in] callbacks Struct containing pointers to callback functions.
+ *                       Can be NULL if no callbacks are defined.
  *
- * @retval 0 If the operation was successful.
- *           Otherwise, a (negative) error code is returned.
+ *  @retval 0 If the operation was successful.
+ *          Otherwise, a negative error code is returned.
  */
 int bt_lbs_init(struct bt_lbs_cb *callbacks);
 

include/bluetooth/services/nus.h

@@ -81,17 +81,17 @@ struct bt_nus_cb {
 
 };
 
-/**@brief Initialize the service.
+/**@brief Initialize the NUS Service.
  *
- * @details This function registers a GATT service with two characteristics,
- *          TX and RX. A remote device that is connected to this service
- *          can send data to the RX Characteristic. When the remote enables
- *          notifications, it is notified when data is sent to the TX
- *          Characteristic.
+ *  Initializes the module with the given callbacks, used when:
+ *  - The RX characteristic is written to by a remote device.
+ *  - The TX characteristic notification state changes.
+ *  - The notification has been sent to a remote device.
  *
- * @param[in] callbacks  Struct with function pointers to callbacks for service
- *                       events. If no callbacks are needed, this parameter can
- *                       be NULL.
+ *  @note The GATT service is defined and registered statically at compile time.
+ *
+ *  @param[in] callbacks Struct containing pointers to callback functions.
+ *                       Can be NULL if no callbacks are defined.
  *
  * @retval 0 If initialization is successful.
  *           Otherwise, a negative value is returned.

include/bluetooth/services/rscs.h

@@ -161,7 +161,7 @@ struct bt_rscs_measurement {
 	uint32_t total_distance;
 };
 
-/** @brief Function for sending Running Speed and Cadence measurement.
+/** @brief Sending Running Speed and Cadence measurement.
  *
  * The application calls this function after having performed a Running Speed and Cadence
  * measurement. If notification has been enabled, the measurement data is encoded
@@ -175,9 +175,13 @@ struct bt_rscs_measurement {
  */
 int bt_rscs_measurement_send(struct bt_conn *conn, const struct bt_rscs_measurement *measurement);
 
-/** @brief Function for initializing the Running Speed and Cadence Service.
+/** @brief Initialize the Running Speed and Cadence Service.
  *
- *  @param[in] init Initialization parameters.
+ *  Initializes the module with the given initialization parameters.
+ *
+ *  @note The GATT service is defined and registered statically at compile time.
+ *
+ *  @param[in] init Initialization parameters. Must not be NULL.
  *
  *  @retval 0 If the operation was successful.
  *          Otherwise, a negative error code is returned.

include/bluetooth/services/throughput.h

@@ -93,10 +93,15 @@ struct bt_throughput {
 #define BT_UUID_THROUGHPUT                                                     \
 	BT_UUID_DECLARE_128(BT_UUID_THROUGHPUT_VAL)
 
-/** @brief Initialize the GATT Throughput Service.
+/** @brief Initialize the GATT Throughput Service instance.
+ *
+ *  Initializes the instance with the given callbacks.
+
+ *  @note The GATT service is defined and registered statically at compile time.
  *
  *  @param[in] throughput Throughput Service instance.
- *  @param[in] cb Callbacks.
+ *  @param[in] cb Struct containing pointers to callback functions.
+ *                Can be NULL if no callbacks are defined.
  *
  *  @retval 0 If the operation was successful.
  *            Otherwise, a negative error code is returned.