Refactored canonical doc for state to lang specific doc

ably/state.go

@@ -344,83 +344,142 @@ func (e ConnectionEventEmitter) listenResult(expected ConnectionState, failed ..
 	})
 }
 
-// A ConnectionState identifies the state of an Ably realtime connection.
-// **CANONICAL**
-// Describes the realtime [Connection]{@link Connection} object states.
+// ConnectionState describes the realtime [ably.Connection] object states.
 type ConnectionState struct {
 	name string
 }
 
 var (
-	// **CANONICAL**
-	// A connection with this state has been initialized but no connection has yet been attempted.
+	// ConnectionStateInitialized - A connection with this state has been initialized
+	// but no connection has yet been attempted.
 	ConnectionStateInitialized  ConnectionState = ConnectionState{name: "INITIALIZED"}
-	// **CANONICAL**
-	// A connection attempt has been initiated. The connecting state is entered as soon as the library has completed initialization, and is reentered each time connection is re-attempted following disconnection.
+
+	// ConnectionStateConnecting - A connection attempt has been initiated.
+	// The connecting state is entered as soon as the library has completed initialization,
+	// and is reentered each time connection is re-attempted following disconnection.
 	ConnectionStateConnecting   ConnectionState = ConnectionState{name: "CONNECTING"}
-	// **CANONICAL**
-	// A connection exists and is active.
+
+	// ConnectionStateConnected - A connection exists and is active.
 	ConnectionStateConnected    ConnectionState = ConnectionState{name: "CONNECTED"}
-	// **CANONICAL**
-	// A temporary failure condition. No current connection exists because there is no network connectivity or no host is available. The disconnected state is entered if an established connection is dropped, or if a connection attempt was unsuccessful. In the disconnected state the library will periodically attempt to open a new connection (approximately every 15 seconds), anticipating that the connection will be re-established soon and thus connection and channel continuity will be possible. In this state, developers can continue to publish messages as they are automatically placed in a local queue, to be sent as soon as a connection is reestablished. Messages published by other clients while this client is disconnected will be delivered to it upon reconnection, so long as the connection was resumed within 2 minutes. After 2 minutes have elapsed, recovery is no longer possible and the connection will move to the SUSPENDED state.
+
+	// ConnectionStateDisconnected - A temporary failure condition. No current connection exists
+	// because there is no network connectivity or no host is available.
+	// The disconnected state is entered if an established connection is dropped,
+	// or if a connection attempt was unsuccessful. In the disconnected state the library will periodically attempt
+	// to open a new connection (approximately every 15 seconds), anticipating that the connection will
+	// be re-established soon and thus connection and channel continuity will be possible.
+	// In this state, developers can continue to publish messages as they are automatically placed in a local queue,
+	// to be sent as soon as a connection is reestablished. Messages published by other clients
+	// while this client is disconnected will be delivered to it upon reconnection, so long as
+	// the connection was resumed within 2 minutes. After 2 minutes have elapsed, recovery is no longer possible
+	// and the connection will move to the SUSPENDED state.
 	ConnectionStateDisconnected ConnectionState = ConnectionState{name: "DISCONNECTED"}
-	// **CANONICAL**
-	// A long term failure condition. No current connection exists because there is no network connectivity or no host is available. The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, the library will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to [connect()]{@link Connection#connect}. Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the History API.
+
+	// ConnectionStateSuspended - A long term failure condition. No current connection exists
+	// because there is no network connectivity or no host is available. The suspended state is entered
+	// after a failed connection attempt if there has then been no connection for a period of two minutes.
+	// In the suspended state, the library will periodically attempt to open a new connection every 30 seconds.
+	// Developers are unable to publish messages in this state. A new connection attempt can also be triggered
+	// by an explicit call to Connection.Connect. Once the connection has been re-established,
+	// channels will be automatically re-attached. The client has been disconnected for too long for them
+	// to resume from where they left off, so if it wants to catch up on messages published by other clients
+	// while it was disconnected, it needs to use the History API.
 	ConnectionStateSuspended    ConnectionState = ConnectionState{name: "SUSPENDED"}
-	// **CANONICAL**
-	// An explicit request by the developer to close the connection has been sent to the Ably service. If a reply is not received from Ably within a short period of time, the connection is forcibly terminated and the connection state becomes CLOSED.
+
+	// ConnectionStateClosing is when an explicit request by the developer to close the connection has been sent to
+	// the Ably service. If a reply is not received from Ably within a short period of time,
+	// the connection is forcibly terminated and the connection state becomes CLOSED.
 	ConnectionStateClosing      ConnectionState = ConnectionState{name: "CLOSING"}
-	// **CANONICAL**
-	// The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. No connection state is preserved by the service or by the library. A new connection attempt can be triggered by an explicit call to [connect()]{@link Connection#connect}, which results in a new connection.
+
+	// ConnectionStateClosed - The connection has been explicitly closed by the client.
+	// In the closed state, no reconnection attempts are made automatically by the library,
+	// and clients may not publish messages. No connection state is preserved by the service or by the library.
+	// A new connection attempt can be triggered by an explicit call to Connection.Connect,
+	// which results in a new connection.
 	ConnectionStateClosed       ConnectionState = ConnectionState{name: "CLOSED"}
-	// **CANONICAL**
-	// This state is entered if the client library encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, for example an attempt to connect with an incorrect API key, or a local terminal error, for example the token in use has expired and the library does not have any way to renew it. In the failed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to [connect()]{@link Connection#connect}.
+
+	// ConnectionStateFailed - This state is entered if the client library encounters a failure condition
+	// that it cannot recover from. This may be a fatal connection error received from the Ably service,
+	// for example an attempt to connect with an incorrect API key, or a local terminal error,
+	// for example the token in use has expired and the library does not have any way to renew it.
+	// In the failed state, no reconnection attempts are made automatically by the library, and
+	// clients may not publish messages. A new connection attempt can be triggered by an explicit call
+	// to Connection.Connect.
 	ConnectionStateFailed       ConnectionState = ConnectionState{name: "FAILED"}
 )
 
 func (e ConnectionState) String() string {
 	return e.name
 }
 
-// **LEGACY**
-// A ConnectionEvent identifies an event in the lifetime of an Ably realtime
-// connection.
-// **CANONICAL**
-// Describes the events emitted by a [Connection]{@link} object. An event is either an UPDATE or a [ConnectionState]{@link ConnectionState}.
+// ConnectionEvent describes the events emitted by a [ably.Connection] object.
+// An event is either an [ably.ConnectionEventUpdate] or [ably.ConnectionState} change event.
 type ConnectionEvent struct {
 	name string
 }
 
 func (ConnectionEvent) isEmitterEvent() {}
 
 var (
-	// **CANONICAL**
-	// A connection with this state has been initialized but no connection has yet been attempted.
+	// ConnectionEventInitialized - A connection with this state has been initialized
+	// but no connection has yet been attempted.
 	ConnectionEventInitialized  ConnectionEvent = ConnectionEvent(ConnectionStateInitialized)
-	// **CANONICAL**
-	// A connection attempt has been initiated. The connecting state is entered as soon as the library has completed initialization, and is reentered each time connection is re-attempted following disconnection.
+
+	// ConnectionEventConnecting - A connection attempt has been initiated.
+	// The connecting state is entered as soon as the library has completed initialization,
+	// and is reentered each time connection is re-attempted following disconnection.
 	ConnectionEventConnecting   ConnectionEvent = ConnectionEvent(ConnectionStateConnecting)
-	// **CANONICAL**
-	// A connection exists and is active.
+
+	// ConnectionEventConnected - A connection exists and is active.
 	ConnectionEventConnected    ConnectionEvent = ConnectionEvent(ConnectionStateConnected)
-	// **CANONICAL**
-	// A temporary failure condition. No current connection exists because there is no network connectivity or no host is available. The disconnected state is entered if an established connection is dropped, or if a connection attempt was unsuccessful. In the disconnected state the library will periodically attempt to open a new connection (approximately every 15 seconds), anticipating that the connection will be re-established soon and thus connection and channel continuity will be possible. In this state, developers can continue to publish messages as they are automatically placed in a local queue, to be sent as soon as a connection is reestablished. Messages published by other clients while this client is disconnected will be delivered to it upon reconnection, so long as the connection was resumed within 2 minutes. After 2 minutes have elapsed, recovery is no longer possible and the connection will move to the SUSPENDED state.
+
+	// ConnectionEventDisconnected - A temporary failure condition. No current connection exists
+	// because there is no network connectivity or no host is available.
+	// The disconnected state is entered if an established connection is dropped,
+	// or if a connection attempt was unsuccessful. In the disconnected state the library will periodically attempt
+	// to open a new connection (approximately every 15 seconds), anticipating that the connection will
+	// be re-established soon and thus connection and channel continuity will be possible.
+	// In this state, developers can continue to publish messages as they are automatically placed in a local queue,
+	// to be sent as soon as a connection is reestablished. Messages published by other clients
+	// while this client is disconnected will be delivered to it upon reconnection, so long as
+	// the connection was resumed within 2 minutes. After 2 minutes have elapsed, recovery is no longer possible
+	// and the connection will move to the SUSPENDED state.
 	ConnectionEventDisconnected ConnectionEvent = ConnectionEvent(ConnectionStateDisconnected)
-	// **CANONICAL**
-	// A long term failure condition. No current connection exists because there is no network connectivity or no host is available. The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, the library will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to [connect()]{@link Connection#connect}. Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the History API.
+
+	// ConnectionEventSuspended - A long term failure condition. No current connection exists
+	// because there is no network connectivity or no host is available. The suspended state is entered
+	// after a failed connection attempt if there has then been no connection for a period of two minutes.
+	// In the suspended state, the library will periodically attempt to open a new connection every 30 seconds.
+	// Developers are unable to publish messages in this state. A new connection attempt can also be triggered
+	// by an explicit call to Connection.Connect. Once the connection has been re-established,
+	// channels will be automatically re-attached. The client has been disconnected for too long for them
+	// to resume from where they left off, so if it wants to catch up on messages published by other clients
+	// while it was disconnected, it needs to use the History API.
 	ConnectionEventSuspended    ConnectionEvent = ConnectionEvent(ConnectionStateSuspended)
-	// **CANONICAL**
-	// An explicit request by the developer to close the connection has been sent to the Ably service. If a reply is not received from Ably within a short period of time, the connection is forcibly terminated and the connection state becomes CLOSED.
+
+	// ConnectionEventClosing is when an explicit request by the developer to close the connection has been sent to
+	// the Ably service. If a reply is not received from Ably within a short period of time,
+	// the connection is forcibly terminated and the connection state becomes CLOSED.
 	ConnectionEventClosing      ConnectionEvent = ConnectionEvent(ConnectionStateClosing)
-	// **CANONICAL**
-	// The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. No connection state is preserved by the service or by the library. A new connection attempt can be triggered by an explicit call to [connect()]{@link Connection#connect}, which results in a new connection.
+
+	// ConnectionEventClosed - The connection has been explicitly closed by the client.
+	// In the closed state, no reconnection attempts are made automatically by the library,
+	// and clients may not publish messages. No connection state is preserved by the service or by the library.
+	// A new connection attempt can be triggered by an explicit call to Connection.Connect,
+	// which results in a new connection.
 	ConnectionEventClosed       ConnectionEvent = ConnectionEvent(ConnectionStateClosed)
-	// **CANONICAL**
-	// This state is entered if the client library encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, for example an attempt to connect with an incorrect API key, or a local terminal error, for example the token in use has expired and the library does not have any way to renew it. In the failed state, no reconnection attempts are made automatically by the library, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to [connect()]{@link Connection#connect}.
+
+	// ConnectionEventFailed - This state is entered if the client library encounters a failure condition
+	// that it cannot recover from. This may be a fatal connection error received from the Ably service,
+	// for example an attempt to connect with an incorrect API key, or a local terminal error,
+	// for example the token in use has expired and the library does not have any way to renew it.
+	// In the failed state, no reconnection attempts are made automatically by the library, and
+	// clients may not publish messages. A new connection attempt can be triggered by an explicit call
+	// to Connection.Connect.
 	ConnectionEventFailed       ConnectionEvent = ConnectionEvent(ConnectionStateFailed)
-	// **CANONICAL**
-	// An event for changes to connection conditions for which the [ConnectionState]{@link ConnectionState} does not change.
-	// RTN4h
+
+	// ConnectionEventUpdate is an event for changes to connection conditions for which the
+	// [ably.ConnectionState] does not change (RTN4h).
 	ConnectionEventUpdate       ConnectionEvent = ConnectionEvent{name: "UPDATE"}
 )
 
@@ -556,45 +615,27 @@ func (e ChannelEvent) String() string {
 	return e.name
 }
 
-// **LEGACY**
+// ChannelStateChange contains state change information emitted by [ably.RESTChannel] and [ably.RealtimeChannel] objects.
 // A ChannelStateChange is the data associated with a ChannelEvent.
-//
-// If the Event is a ChannelEventUpdated, Current and Previous are the
-// the same. Otherwise, the event is a state transition from Previous to
-// Current.
-// **CANONICAL**
-// Contains state change information emitted by [RestChannel]{@link RestChannel} and [RealtimeChannel]{@link RealtimeChannel} objects.
-
 type ChannelStateChange struct {
-	// **CANONICAL**
-	// The new current [ChannelState]{@link ChannelState}.
-	// RTL2a, RTL2b
+
+	// Current is the new current [ably.ChannelState] (RTL2a, RTL2b).
 	Current  ChannelState
 
-	// **CANONICAL**
-	// The event that triggered this [ChannelState]{@link ChannelState} change.
-	// TH5
+	// Event is the event that triggered this [ably.ChannelState] change (TH5).
 	Event    ChannelEvent
 
-	// **CANONICAL**
-	// The previous state. For the [UPDATE]{@link ChannelEvent#UPDATE} event, this is equal to the current [ChannelState]{@link ChannelState}.
-	// RTL2a, RTL2b
+	// Previous is the previous state.
+	// For the [ably.ChannelEventUpdate] event, this is equal to the current [ably.ChannelState] (RTL2a, RTL2b).
 	Previous ChannelState
 
-	// **LEGACY**
-	// Reason, if any, is an error that caused the state change.
-	// **CANONICAL**
-	// An [ErrorInfo]{@link ErrorInfo} object containing any information relating to the transition.
-	// RTL2e, TH3
+	// Reason is an [ErrorInfo] object that caused the state change (RTL2e, TH3).
 	Reason *ErrorInfo
 
-	// **LEGACY**
-	// Resumed is set to true for Attached and Update events when channel state
-	// has been maintained without interruption in the server, so there has
-	// been no loss of message continuity.
-	// **CANONICAL**
+	// Resumed is set to true for Attached and Update events when channel state has been maintained
+	// without interruption in the server, so there has been no loss of message continuity.
 	// Indicates whether message continuity on this channel is preserved, see Nonfatal channel errors for more info.
-	// RTL2f, TH4
+	// (RTL2f, TH4)
 	Resumed bool
 }