[EventHub] update get_buffered_event_count docstring (#24756)

sdk/eventhub/azure-eventhub/azure/eventhub/_producer_client.py

@@ -830,9 +830,12 @@ def close(self, *, flush: bool = True, **kwargs: Any) -> None:
     def get_buffered_event_count(self, partition_id: str) -> Optional[int]:
         """
         The number of events that are buffered and waiting to be published for a given partition.
-         Returns None in non-buffered mode. **NOTE: This method should only be used for debugging
-         purposes. If an invalid `partition_id` is passed in, then a value of 0 will be returned
-         which may be misleading.**
+         Returns None in non-buffered mode. **NOTE: The event buffer is processed in a background
+         thread, therefore the number of events in the buffer reported by this API should be
+         considered only an approximation and is only recommend for use in debugging. For a
+         partition ID that has no events buffered, 0 will be returned regardless of whether that
+         partition ID actually exists within the Event Hub.**
+
 
         :param str partition_id: The target partition ID.
         :rtype: int or None
@@ -851,10 +854,10 @@ def get_buffered_event_count(self, partition_id: str) -> Optional[int]:
     def total_buffered_event_count(self) -> Optional[int]:
         """
         The total number of events that are currently buffered and waiting to be published,
-         across all partitions. Returns None in non-buffered mode. **NOTE: This method should
-         only be used for debugging purposes. If an invalid `partition_id` is passed in,
-         then a value of 0 will be returned which may be misleading.**
-
+         across all partitions. Returns None in non-buffered mode. **NOTE: The event buffer
+         is processed in a background thread, therefore the number of events in the buffer
+         reported by this API should be considered only an approximation and is only recommend
+         for use in debugging.**
 
         :rtype: int or None
         """

sdk/eventhub/azure-eventhub/azure/eventhub/aio/_producer_client_async.py

@@ -827,10 +827,11 @@ async def close(self, *, flush: bool = True, **kwargs: Any) -> None:
     def get_buffered_event_count(self, partition_id: str) -> Optional[int]:
         """
         The number of events that are buffered and waiting to be published for a given partition.
-         Returns None in non-buffered mode. **NOTE: This method should only be used for debugging
-         purposes. If an invalid `partition_id` is passed in, then a value of 0 will be returned
-         which may be misleading.**
-
+         Returns None in non-buffered mode. **NOTE: The event buffer is processed in a background
+         coroutine, therefore the number of events in the buffer reported by this API should be
+         considered only an approximation and is only recommend for use in debugging. For a
+         partition ID that has no events buffered, 0 will be returned regardless of whether that
+         partition ID actually exists within the Event Hub.**
 
         :param str partition_id: The target partition ID.
         :rtype: int or None
@@ -849,10 +850,10 @@ def get_buffered_event_count(self, partition_id: str) -> Optional[int]:
     def total_buffered_event_count(self) -> Optional[int]:
         """
         The total number of events that are currently buffered and waiting to be published,
-         across all partitions. Returns None in non-buffered mode. **NOTE: This method should
-         only be used for debugging purposes. If an invalid `partition_id` is passed in,
-         then a value of 0 will be returned which may be misleading.**
-
+         across all partitions. Returns None in non-buffered mode. **NOTE: The event buffer
+         is processed in a background coroutine, therefore the number of events in the buffer
+         reported by this API should be considered only an approximation and is only recommend
+         for use in debugging.**
 
         :rtype: int or None
         """