https://github.com/ably/docs/pull/112#discussion_r61354799

textile/features.textile

@@ -302,7 +302,7 @@ h3(#realtime-connection). Connection
 ** @(RTN10c)@ The last known @ProtocolMessage@ @connectionSerial@ is used when restoring connection state
 * @(RTN11)@ @Connection#connect@ function:
 ** @(RTN11a)@ Explicitly connects to the Ably service if not already connected
-** @(RTN11b)@ An error will be indicated if the state is @CLOSING@ as the connection must complete the close request before reconnecting
+** @(RTN11b)@ If the state is @CLOSING@, the client can reuse the transport and make a new connection with it, but it should make sure that, when the @CLOSED@ @ProtocolMessage@ arrives for the old connection, it doesn't affect the new one.
 * @(RTN12)@ @Connection#close@ function:
 ** @(RTN12f)@ If the connection state is @CONNECTING@, do the operation once the connection state is @CONNECTED@
 ** @(RTN12a)@ If the connection state is @CONNECTED@, sends a @CLOSE@ @ProtocolMessage@ to the server, sets the state to @CLOSING@ and waits for a @CLOSED@ @ProtocolMessage@ to be received
@@ -384,7 +384,7 @@ h3(#realtime-channel). Channel
 * @(RTL11)@ If a channel enters the @DETACHED@ or @FAILED@ state, then all messages that are still queued for send on that channel should be deleted from the queue triggering a failure for the publish or presence methods invoked for those messages
 * @(RTL4)@ @Channel#attach@ function:
 ** @(RTL4a)@ If already @ATTACHED@ or @ATTACHING@ nothing is done
-** @(RTL4e)@ If the channel is in the @DETACHING@ state, it will result in an error, as the channel must complete the detach request before reattaching
+** @(RTL4e)@ If the channel is in the @DETACHING@ state, do the operation once it's @DETACHED@.
 ** @(RTL4g)@ If state is @FAILED@, the @attach@ request results in an error
 ** @(RTL4b)@ If the connection state is @CLOSED@, @CLOSING@, @SUSPENDED@ or @FAILED@, the @attach@ request results in an error
 ** @(RTL4h)@ If the connection state is @INITIALIZED@, @CONNECTING@ or @DISCONNECTED@, do the operation once the connection state is @CONNECTED@