Bluetooth:Doc: Clarify GATT API

Clarifies what does start_handle and end_handle means in the GATT API.

Signed-off-by: Omkar Kulkarni <[email protected]>

Author: omkar3141

include/zephyr/bluetooth/gatt.h

@@ -330,9 +330,9 @@ struct bt_gatt_service_val {
 struct bt_gatt_include {
 	/** Service UUID. */
 	const struct bt_uuid *uuid;
-	/** Service start handle. */
+	/** Starting attribute handle for included service. */
 	uint16_t start_handle;
-	/** Service end handle. */
+	/** Ending attribute handle for included service. */
 	uint16_t end_handle;
 };
 
@@ -633,8 +633,8 @@ typedef uint8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr,
  *
  *  Iterate attributes in the given range matching given UUID and/or data.
  *
- *  @param start_handle Start handle.
- *  @param end_handle End handle.
+ *  @param start_handle Starting attribute handle.
+ *  @param end_handle Ending attribute handle.
  *  @param uuid UUID to match, passing NULL skips UUID matching.
  *  @param attr_data Attribute data to match, passing NULL skips data matching.
  *  @param num_matches Number matches, passing 0 makes it unlimited.
@@ -651,8 +651,8 @@ void bt_gatt_foreach_attr_type(uint16_t start_handle, uint16_t end_handle,
  *
  *  Iterate attributes in the given range.
  *
- *  @param start_handle Start handle.
- *  @param end_handle End handle.
+ *  @param start_handle Starting attribute handle.
+ *  @param end_handle Ending attribute handle.
  *  @param func Callback function.
  *  @param user_data Data to pass to the callback.
  */
@@ -1657,15 +1657,23 @@ struct bt_gatt_discover_params {
 		struct {
 			/** Include service attribute declaration handle */
 			uint16_t attr_handle;
-			/** Included service start handle */
+			/** Starting attribute handle for included service */
 			uint16_t start_handle;
-			/** Included service end handle */
+			/** Ending attribute handle for included service */
 			uint16_t end_handle;
 		} _included;
-		/** Discover start handle */
+		/** Starting attribute handle to begin discovery
+		 * 
+		 * @note When discovery begins in @ref bt_conn_cb.connected callback this is 
+		 * typically set to @ref BT_ATT_FIRST_ATTRIBUTE_HANDLE
+		 */
 		uint16_t start_handle;
 	};
-	/** Discover end handle */
+	/** Ending attribute handle to stop discovery at
+	 * 
+	 * @note When discovery begins in @ref bt_conn_cb.connected callback this is 
+	 * typically set to @ref BT_ATT_LAST_ATTRIBUTE_HANDLE
+	 */
 	uint16_t end_handle;
 	/** Discover type */
 	uint8_t type;
@@ -1772,9 +1780,17 @@ struct bt_gatt_read_params {
 			bool variable;
 		} multiple;
 		struct {
-			/** First requested handle number. */
+			/** First requested attribute handle number. 
+			 * 
+			 * @note When attributes are read by UUID, this is typically set to 
+			 * @ref BT_ATT_FIRST_ATTRIBUTE_HANDLE.
+			 */
 			uint16_t start_handle;
-			/** Last requested handle number. */
+			/** Last requested attribute handle number. 
+			 * 
+			 * @note When attributes are read by UUID, this is typically set to 
+			 * @ref BT_ATT_LAST_ATTRIBUTE_HANDLE.
+			 */
 			uint16_t end_handle;
 			/** 2 or 16 octet UUID. */
 			const struct bt_uuid *uuid;
@@ -1789,7 +1805,7 @@ struct bt_gatt_read_params {
 
 /** @brief Read Attribute Value by handle
  *
- *  This procedure read the attribute value and return it to the callback.
+ *  This procedure reads the attribute value and returns it to the callback.
  *
  *  When reading attributes by UUID the callback can be called multiple times
  *  depending on how many instances of given the UUID exists with the