Fix recoveryKey docstrings and clarify that REC1b2 endpoint has no port

specifications/api-docstrings.md

@@ -958,8 +958,8 @@ Enables the management of a connection to Ably.
 | errorReason: ErrorInfo? ||| RTN14a | An [`ErrorInfo`]{@link ErrorInfo} object describing the last error received if a connection failure occurs. |
 | id: String? ||| RTN8 | A unique public identifier for this connection, used to identify this member. |
 | key: String? ||| RTN9 | A unique private connection key used to recover or resume a connection, assigned by Ably. When recovering a connection explicitly, the `recoveryKey` is used in the recover client options as it contains both the key and the last message serial. This private connection key can also be used by other REST clients to publish on behalf of this client. See the [publishing over REST on behalf of a realtime client docs](https://ably.com/docs/rest/channels#publish-on-behalf) for more info. |
-| recoveryKey: String? ||| RTN16b, RTN16c | This property is deprecated and will be removed in future versions of the library. You should use [`createRecoveryKey`]{@link Connection#createRecoveryKey} method instead. |
-| createRecoveryKey: String? ||| RTN16b, RTN16c | The recovery key string can be used by another client to recover this connection's state using the [`ClientOptions.recover`]{@ link ClientOptions#recover} property. It will return `nil` if connection is in the [`CLOSED`]{@link ConnectionState#CLOSED}, [`CLOSING`]{@link ConnectionState#CLOSING}, [`FAILED`]{@link ConnectionState#FAILED}, or [`SUSPENDED`]{@link ConnectionState#SUSPENDED} states, or when it does not have a connection [`key`]{@link Connection#key} (for example, if it has not yet become connected). See [connection state recovery options](ably.com/docs/connect/states) for more information. |
+| recoveryKey: String? ||| RTN16g | This property is deprecated and will be removed in future versions of the library. You should use [`createRecoveryKey`]{@link Connection#createRecoveryKey} method instead. |
+| createRecoveryKey: String? ||| RTN16g, RTN16g3 | The recovery key string can be used by another client to recover this connection's state using the [`ClientOptions.recover`]{@ link ClientOptions#recover} property. It will return `nil` if connection is in the [`CLOSED`]{@link ConnectionState#CLOSED}, [`CLOSING`]{@link ConnectionState#CLOSING}, [`FAILED`]{@link ConnectionState#FAILED}, or [`SUSPENDED`]{@link ConnectionState#SUSPENDED} states, or when it does not have a connection [`key`]{@link Connection#key} (for example, if it has not yet become connected). See [connection state recovery options](ably.com/docs/connect/states) for more information. |
 | serial: Int? ||| RTN10 | The serial number of the last message to be received on this connection, used automatically by the library when recovering or resuming a connection. When recovering a connection explicitly, the `recoveryKey` is used in the recover client options as it contains both the key and the last message serial. |
 | state: ConnectionState ||| RTN4d | The current [`ConnectionState`]{@link ConnectionState} of the connection. |
 | whenState(ConnectionState, (ConnectionStateChange?) ->) ||| RTN26 | If the connection is already in the given state, calls the listener immediately with a `null` argument. Else, calls [`once()`]{@link EventEmitter#once} to register the listener to be called the next time the connection transitions to the given state. |

specifications/features.md

@@ -38,7 +38,7 @@ Support for the deprecated client options `environment`, `restHost`, `realtimeHo
   - `(REC1a)` The `primary domain` is `main.realtime.ably.net` unless overridden by specifying an `endpoint` option or, optionally, any of the deprecated options `environment`, `restHost`, `realtimeHost`.
   - `(REC1b)` If the `endpoint` option is specified then:
     - `(REC1b1)` **(optional, deprecated)** If any one of the deprecated options `environment`, `restHost`, `realtimeHost` or `fallbackHostsUseDefault` are also specified then the options as a set are invalid. This check only applies to client libraries that support these deprecated options.
-    - `(REC1b2)` If the `endpoint` option is a hostname, determined by it containing at least one period (`.`), or containing at least one instance of the string `::`, or being equal to the string `localhost`, then the `primary domain` is the value of the `endpoint` option.
+    - `(REC1b2)` If the `endpoint` option is a hostname, determined by it containing at least one period (`.`), or containing at least one instance of the string `::`, or being equal to the string `localhost`, then the `primary domain` is the value of the `endpoint` option. (Non-normative: the `endpoint` option identifies a host or routing policy only and does not itself carry a port; a non-default port is set with the `port` ([`TO3k4`](#TO3k4)) or `tlsPort` ([`TO3k5`](#TO3k5)) option. For example, `localhost:8080` is not a hostname under this rule, so [`REC1b4`](#REC1b4) treats it as a routing policy ID.)
     - `(REC1b3)` Otherwise, if the `endpoint` option specifies a non-production routing policy ID, determined by it having the form `nonprod:[id]`, then the `primary domain` is `[id].realtime.ably-nonprod.net`.
     - `(REC1b4)` Otherwise, the `endpoint` option is a production routing policy ID of the form `[id]`, and the `primary domain` is `[id].realtime.ably.net`.
   - `(REC1c)` **(optional, deprecated)** If the deprecated `environment` option is specified then it defines a production routing policy ID `[id]`: