docs: 📝 Better documentation for latency properties (#2653)

📝 Better documentation for latency methods

Author: Paillat-dev

discord/client.py

@@ -310,7 +310,8 @@ def _handle_ready(self) -> None:
 
     @property
     def latency(self) -> float:
-        """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
+        """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. If no websocket
+        is present, this returns ``nan``, and if no heartbeat has been received yet, this returns ``float('inf')``.
 
         This could be referred to as the Discord WebSocket protocol latency.
         """

discord/gateway.py

@@ -581,7 +581,9 @@ async def received_message(self, msg, /):
 
     @property
     def latency(self) -> float:
-        """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds."""
+        """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. If no heartbeat
+        has been received yet this returns ``float('inf')``.
+        """
         heartbeat = self._keep_alive
         return float("inf") if heartbeat is None else heartbeat.latency
 

discord/shard.py

@@ -294,7 +294,9 @@ async def connect(self) -> None:
 
     @property
     def latency(self) -> float:
-        """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds for this shard."""
+        """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds for this shard. If no heartbeat
+        has been received yet this returns ``float('inf')``.
+        """
         return self._parent.ws.latency
 
     def is_ws_ratelimited(self) -> bool: