diff --git a/docs/api.rst b/docs/api.rst
index 0421d5a99..35da0571a 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -200,11 +200,11 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
 .. function:: on_disconnect()
 
-    Called when the client has disconnected from Discord. This could happen either through
-    the internet being disconnected, explicit calls to logout, or Discord terminating the connection
-    one way or the other.
+    Called when the client has disconnected from Discord, or a connection attempt to Discord has failed. 
+    This could happen either through the internet being disconnected, explicit calls to logout,
+    or Discord terminating the connection one way or the other.
 
-    This function can be called many times.
+    This function can be called many times without a corresponding :func:`on_connect` call.
 
 .. function:: on_shard_disconnect(shard_id)