Document connection state transition timing

docs/source/api.rst

@@ -23,6 +23,12 @@ Connection
    :special-members: __init__
    :members:
 
+Incoming bytes are parsed by ``receive_data()``, but state changes caused by
+received events are applied while ``events()`` is consumed. For example, when
+the remote peer sends a close frame, the connection enters
+``REMOTE_CLOSING`` when the corresponding ``CloseConnection`` event is yielded,
+not when the bytes are first passed to ``receive_data()``.
+
 .. autoclass:: wsproto.ConnectionType
    :members:
 

src/wsproto/connection.py

@@ -126,6 +126,11 @@ def receive_data(self, data: bytes | None) -> None:
 
         A list of events that the remote peer triggered by sending this data can
         be retrieved with :meth:`~wsproto.connection.Connection.events`.
+        Passing bytes here does not itself apply every state transition caused
+        by those events. For example, a remote close frame changes the
+        connection state when its corresponding
+        :class:`~wsproto.events.CloseConnection` event is yielded from
+        :meth:`~wsproto.connection.Connection.events`.
 
         :param data: The data received from the remote peer on the network.
         :type data: ``bytes``
@@ -152,6 +157,12 @@ def events(self) -> Generator[Event, None, None]:
         Return a generator that provides any events that have been generated
         by protocol activity.
 
+        Iterating this generator can advance the connection state while
+        received frames are converted into events. For example, yielding a
+        remote :class:`~wsproto.events.CloseConnection` event moves the
+        connection into
+        :attr:`~wsproto.connection.ConnectionState.REMOTE_CLOSING`.
+
         :returns: generator of :class:`Event <wsproto.events.Event>` subclasses
         """
         while self._events: