Fix for duplicate spec IDs (shared with Realtime Connection)

content/client-lib-development-guide/features.textile

@@ -281,52 +281,52 @@ h3(#realtime-channels). Channels
 
 h3(#realtime-channel). Channel
 
-* @(RTN1)@ As soon as a @Channel@ becomes attached, all incoming messages and presence messages are processed and emitted where applicable.  @PRESENCE@ and @SYNC@ messages are passed to the @Presence@ object ensuring it maintains a map of current members on a channel in realtime.
-* @(RTN2)@ EventEmitter and states:
-** @(RTN2a)@ Implements @EventEmitter@ and emits events for state changes @INITIALIZED@, @ATTACHING@, @ATTACHED@, @DETACHING@, @DETACHED@, @FAILED@
-** @(RTN2b)@ @Channel#state@ attribute is the current state of the channel
-** @(RTN2c)@ Additionally, an @ERROR@ event is emitted that contains an @ErrorInfo@ object with details on an error that has occurred for the @Channel@
-* @(RTN3)@ Connection state change side effects:
-** @(RTN3a)@ If the connection state changes to @FAILED@ then an @ATTACHING@ or @ATTACHED@ channel state will transition to @FAILED@, set the @errorReason@ and emit the error event
-** @(RTN3b)@ If the connection state changes to @CLOSED@ then an @ATTACHING@ or @ATTACHED@ channel state will transition to @CLOSED@
-* @(RTN4)@ @Channel#attach@ function:
-** @(RTN4a)@ If already @ATTACHED@ or @ATTACHING@ nothing is done
-** @(RTN4b)@ If the connection state is @CLOSED@, @CLOSING@, @SUSPENDED@ or @FAILED@, an exception should be thrown immediately
-** @(RTN4c)@ Otherwise an @ATTACH@ ProtocolMessage is sent to the server, the state changes to @ATTACHING@ and the channel becomes @ATTACHED@ when the confirmation @ATTACHED@ ProtocolMessage is received
-** @(RTN4d)@ If the language permits, a callback can be provided that is called when the channel is attached successfully or the attach fails and the the @ErrorInfo@ error is passed as an argument to the callback.
-** @(RTN4e)@ If the user does not have sufficient permissions to attach to the channel, the channel state @FAILED@ is emitted with the error @ErrorInfo@. An error event is also emitted, and the @errorReason@ attribute of the @Channel@ is set to the error @ErrorInfo@ object
-* @(RTN5)@ @Channel#detach@ function:
-** @(RTN5a)@ If state is @INITIALISED@, @DETACHED@ or @DETACHING@ nothing is done
-** @(RTN5b)@ If state is @FAILED@ an exception should be thrown immediately
-** @(RTN5d)@ Otherwise a @DETACH@ ProtocolMessage is sent to the server, the state changes to @DETACHING@ and the channel becomes @DETACHED@ when the confirmation @DETACHED@ ProtocolMessage is received
-** @(RTN5e)@ If the language permits, a callback can be provided that is called when the channel is detached successfully or the detach fails and the the @ErrorInfo@ error is passed as an argument to the callback.
-* @(RTN6)@ @Channel#publish@ function:
-** @(RTN6a)@ Messages are encoded in the same way as the REST @Channel#publish@ method
-** @(RTN6b)@ An optional callback can be provided to the @#publish@ method that is called when the message is successfully delivered or upon failure with the appropriate @ErrorInfo@ error. A test should exist to publish lots of messages on a few connections to ensure all message success callbacks are called for all messages published
-** @(RTN6c)@ Connection state conditions:
-*** @(RTN6c1)@ If the connection is @CONNECTED@ then the messages are published immediately
-*** @(RTN6c2)@ If the connection is @CONNECTING@ or @DISCONNECTED@, and @ClientOptions#queueMessages@ has not been explicitly set to false, then the message will be queued and delivered as soon as the connection state returns to @CONNECTED@
-*** @(RTN6c3)@ Else an exception is raised preventing the message publishing
-** @(RTN6d)@ Messages are delivered using a single @ProtocolMessage@ where possible by bundling in all messages for that channel into the @ProtocolMessage#messages@ array. However, a yet to be implemented feature should limit the total number of messages bundled per @ProtocolMessage@ based on the default max message size, and would raise an exception if any single message exceeds that limit
-** @(RTN6e)@ If token auth is being used along with a @clientId@, the @clientId@ will be present on any messages published. A test should exist that connects with a @clientId@, publishes a message on a channel, and with another client, the message should be received with the correct @clientId@ attribute of the message
-** @(RTN6f)@ @Message#connectionId@ should match the current @Connection#id@ for all published messages, a test should exist to ensure the @connectionId@ for received messages matches that of the publisher
-* @(RTN7)@ @Channel#subscribe@ function:
-** @(RTN7a)@ Subscribe with no arguments subscribes a listener to all messages
-** @(RTN7b)@ Subscribe with a single name argument subscribes a listener to only messages whose @name@ member matches the string name
-** @(RTN7c)@ Implicitly attaches the channel if not attached
-** @(RTN7d)@ Messages delivered are automatically decoded based on the @encoding@ attribute; see REST @Channel@ encoding features. If there is an error decoding a message, the message is still delivered, but in addition to sending an error message to the logger, an @ErrorInfo@ error object is emitted as an error on the @Channel@. Tests should exist to publish and subscribe to encoded messages using the "AES 128":https://github.com/ably/ably-common/blob/master/test-resources/crypto-data-128.json and "AES 256":https://github.com/ably/ably-common/blob/master/test-resources/crypto-data-256.json fixture test data
-** @(RTN7e)@ If a message cannot be decoded or decrypted successfully, it should be delivered to the listener with the @encoding@ attribute set indicating the residual encoding state, and an error should be emitted on the channel
-** @(RTN7f)@ A test should exist ensuring published messages are not echoed back to the subscriber when @echoMessages@ is set to false in the @Realtime@ library constructor
-* @(RTN8)@ @Channel#unsubscribe@ function:
-** @(RTN8a)@ Unsubscribe with no arguments unsubscribes the provided listener to all messages if subscribed
-** @(RTN8b)@ Unsubscribe with a single name argument unsubscribes the provided listener if previously subscribed with a name-specific subscription
-* @(RTN9)@ @Channel#presence@ attribute:
-** @(RTN9a)@ Returns the @Presence@ object for this channel
-* @(RTN10)@ @Channel#history@ function:
-** @(RTN10a)@ Supports all the same params as REST @Channel#history@
-** @(RTN10b)@ Additionally supports the param @untilAttach@, which if true, will only retrive messages prior to the moment that the channel was attached. This bound is specified by passing the querystring param @from_serial@ with the serial number assigned to the channel in the @ATTACHED@ @ProtocolMessage@. If the @untilAttach@ param is specified when the channel is not attached an exception should be raised.
-** @(RTN10c)@ Returns a @PaginatedResult@ page containing the first page of messages in the @PaginatedResult#items@ attribute returned from the history request.
-** @(RTN10d)@ A test should exist that publishes messages from one client, and upon confirmation of message delivery, a history request should be made on another client to ensure all messages are available
+* @(RTL1)@ As soon as a @Channel@ becomes attached, all incoming messages and presence messages are processed and emitted where applicable.  @PRESENCE@ and @SYNC@ messages are passed to the @Presence@ object ensuring it maintains a map of current members on a channel in realtime.
+* @(RTL2)@ EventEmitter and states:
+** @(RTL2a)@ Implements @EventEmitter@ and emits events for state changes @INITIALIZED@, @ATTACHING@, @ATTACHED@, @DETACHING@, @DETACHED@, @FAILED@
+** @(RTL2b)@ @Channel#state@ attribute is the current state of the channel
+** @(RTL2c)@ Additionally, an @ERROR@ event is emitted that contains an @ErrorInfo@ object with details on an error that has occurred for the @Channel@
+* @(RTL3)@ Connection state change side effects:
+** @(RTL3a)@ If the connection state changes to @FAILED@ then an @ATTACHING@ or @ATTACHED@ channel state will transition to @FAILED@, set the @errorReason@ and emit the error event
+** @(RTL3b)@ If the connection state changes to @CLOSED@ then an @ATTACHING@ or @ATTACHED@ channel state will transition to @CLOSED@
+* @(RTL4)@ @Channel#attach@ function:
+** @(RTL4a)@ If already @ATTACHED@ or @ATTACHING@ nothing is done
+** @(RTL4b)@ If the connection state is @CLOSED@, @CLOSING@, @SUSPENDED@ or @FAILED@, an exception should be thrown immediately
+** @(RTL4c)@ Otherwise an @ATTACH@ ProtocolMessage is sent to the server, the state changes to @ATTACHING@ and the channel becomes @ATTACHED@ when the confirmation @ATTACHED@ ProtocolMessage is received
+** @(RTL4d)@ If the language permits, a callback can be provided that is called when the channel is attached successfully or the attach fails and the the @ErrorInfo@ error is passed as an argument to the callback.
+** @(RTL4e)@ If the user does not have sufficient permissions to attach to the channel, the channel state @FAILED@ is emitted with the error @ErrorInfo@. An error event is also emitted, and the @errorReason@ attribute of the @Channel@ is set to the error @ErrorInfo@ object
+* @(RTL5)@ @Channel#detach@ function:
+** @(RTL5a)@ If state is @INITIALISED@, @DETACHED@ or @DETACHING@ nothing is done
+** @(RTL5b)@ If state is @FAILED@ an exception should be thrown immediately
+** @(RTL5d)@ Otherwise a @DETACH@ ProtocolMessage is sent to the server, the state changes to @DETACHING@ and the channel becomes @DETACHED@ when the confirmation @DETACHED@ ProtocolMessage is received
+** @(RTL5e)@ If the language permits, a callback can be provided that is called when the channel is detached successfully or the detach fails and the the @ErrorInfo@ error is passed as an argument to the callback.
+* @(RTL6)@ @Channel#publish@ function:
+** @(RTL6a)@ Messages are encoded in the same way as the REST @Channel#publish@ method
+** @(RTL6b)@ An optional callback can be provided to the @#publish@ method that is called when the message is successfully delivered or upon failure with the appropriate @ErrorInfo@ error. A test should exist to publish lots of messages on a few connections to ensure all message success callbacks are called for all messages published
+** @(RTL6c)@ Connection state conditions:
+*** @(RTL6c1)@ If the connection is @CONNECTED@ then the messages are published immediately
+*** @(RTL6c2)@ If the connection is @CONNECTING@ or @DISCONNECTED@, and @ClientOptions#queueMessages@ has not been explicitly set to false, then the message will be queued and delivered as soon as the connection state returns to @CONNECTED@
+*** @(RTL6c3)@ Else an exception is raised preventing the message publishing
+** @(RTL6d)@ Messages are delivered using a single @ProtocolMessage@ where possible by bundling in all messages for that channel into the @ProtocolMessage#messages@ array. However, a yet to be implemented feature should limit the total number of messages bundled per @ProtocolMessage@ based on the default max message size, and would raise an exception if any single message exceeds that limit
+** @(RTL6e)@ If token auth is being used along with a @clientId@, the @clientId@ will be present on any messages published. A test should exist that connects with a @clientId@, publishes a message on a channel, and with another client, the message should be received with the correct @clientId@ attribute of the message
+** @(RTL6f)@ @Message#connectionId@ should match the current @Connection#id@ for all published messages, a test should exist to ensure the @connectionId@ for received messages matches that of the publisher
+* @(RTL7)@ @Channel#subscribe@ function:
+** @(RTL7a)@ Subscribe with no arguments subscribes a listener to all messages
+** @(RTL7b)@ Subscribe with a single name argument subscribes a listener to only messages whose @name@ member matches the string name
+** @(RTL7c)@ Implicitly attaches the channel if not attached
+** @(RTL7d)@ Messages delivered are automatically decoded based on the @encoding@ attribute; see REST @Channel@ encoding features. If there is an error decoding a message, the message is still delivered, but in addition to sending an error message to the logger, an @ErrorInfo@ error object is emitted as an error on the @Channel@. Tests should exist to publish and subscribe to encoded messages using the "AES 128":https://github.com/ably/ably-common/blob/master/test-resources/crypto-data-128.json and "AES 256":https://github.com/ably/ably-common/blob/master/test-resources/crypto-data-256.json fixture test data
+** @(RTL7e)@ If a message cannot be decoded or decrypted successfully, it should be delivered to the listener with the @encoding@ attribute set indicating the residual encoding state, and an error should be emitted on the channel
+** @(RTL7f)@ A test should exist ensuring published messages are not echoed back to the subscriber when @echoMessages@ is set to false in the @Realtime@ library constructor
+* @(RTL8)@ @Channel#unsubscribe@ function:
+** @(RTL8a)@ Unsubscribe with no arguments unsubscribes the provided listener to all messages if subscribed
+** @(RTL8b)@ Unsubscribe with a single name argument unsubscribes the provided listener if previously subscribed with a name-specific subscription
+* @(RTL9)@ @Channel#presence@ attribute:
+** @(RTL9a)@ Returns the @Presence@ object for this channel
+* @(RTL10)@ @Channel#history@ function:
+** @(RTL10a)@ Supports all the same params as REST @Channel#history@
+** @(RTL10b)@ Additionally supports the param @untilAttach@, which if true, will only retrive messages prior to the moment that the channel was attached. This bound is specified by passing the querystring param @from_serial@ with the serial number assigned to the channel in the @ATTACHED@ @ProtocolMessage@. If the @untilAttach@ param is specified when the channel is not attached an exception should be raised.
+** @(RTL10c)@ Returns a @PaginatedResult@ page containing the first page of messages in the @PaginatedResult#items@ attribute returned from the history request.
+** @(RTL10d)@ A test should exist that publishes messages from one client, and upon confirmation of message delivery, a history request should be made on another client to ensure all messages are available
 
 h3(#realtime-presence). Presence