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,33 @@ 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. During discovery
+		 * process this should be set to the next handle value of
+		 * the recently discovered attribute (e.g.
+		 * @ref bt_gatt_attr.handle + 1) and discover attribute
+		 * callback should return @ref BT_GATT_ITER_CONTINUE to
+		 * continue discovery or @ref BT_GATT_ITER_STOP to stop
+		 * discovery.
+		 * During iterative discovery of attributes by service types,
+		 * this handle is incremented internally by stack.
+		 */
 		uint16_t start_handle;
 	};
-	/** Discover end handle */
+	/** Ending attribute handle to stop discovery at
+	 *
+	 * @note When discovery begins this can be set to
+	 * @ref BT_ATT_LAST_ATTRIBUTE_HANDLE to discover all attributes
+	 * in the service.
+	 */
 	uint16_t end_handle;
 	/** Discover type */
 	uint8_t type;
@@ -1772,9 +1790,33 @@ struct bt_gatt_read_params {
 			bool variable;
 		} multiple;
 		struct {
-			/** First requested handle number. */
+			/** First requested attribute handle number.
+			 *
+			 * @note The starting handle is set to the starting
+			 * point of the range over which this read should
+			 * be performed. For example, this could be set to
+			 * @ref BT_ATT_FIRST_ATTRIBUTE_HANDLE to set the
+			 * starting point of the range at the beginning of
+			 * the GATT database, or to the starting handle of a
+			 * service after discovery.
+			 *
+			 * @note This value is also automatically
+			 * incremented by the stack after processing each
+			 * matching handle-value pair returned by the
+			 * server.
+			 */
 			uint16_t start_handle;
-			/** Last requested handle number. */
+			/** Last requested attribute handle number.
+			 *
+			 * @note The ending handle is set to the ending
+			 * point of the range over which this read should
+			 * be performed. For example, this could be set to
+			 * @ref BT_ATT_LAST_ATTRIBUTE_HANDLE to set the
+			 * ending point of the range at the end of the GATT
+			 * database, or to the end handle service after discovery
+			 * where the end_handle is available in the
+			 * @ref bt_gatt_service_val.
+			 */
 			uint16_t end_handle;
 			/** 2 or 16 octet UUID. */
 			const struct bt_uuid *uuid;
@@ -1789,7 +1831,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