Merge pull request #36 from ably/docstrings-for-createRecoveryKey

Added docstrings for createRecoveryKey.

descriptions.md

@@ -677,7 +677,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 | The recovery key string can be used by another client to recover this connection's state in the recover client options property. See [connection state recover options](https://ably.com/docs/realtime/connection#connection-state-recover-options) for more information. |
+| 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. |
 | 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. |
 | close() ||| RTN12 | Causes the connection to close, entering the [`CLOSING`]{@link ConnectionState#CLOSING} state. Once closed, the library does not attempt to re-establish the connection without an explicit call to [`connect()`]{@link Connection#connect}. |