ably 1.2.2 → 1.2.3

data/lib/ably/realtime/connection.rb

@@ -2,39 +2,7 @@ require 'securerandom'
 
 module Ably
   module Realtime
-    # The Connection class represents the connection associated with an Ably Realtime instance.
-    # The Connection object exposes the lifecycle and parameters of the realtime connection.
-    #
-    # Connections will always be in one of the following states:
-    #
-    #   initialized:  0
-    #   connecting:   1
-    #   connected:    2
-    #   disconnected: 3
-    #   suspended:    4
-    #   closing:      5
-    #   closed:       6
-    #   failed:       7
-    #
-    # Note that the states are available as Enum-like constants:
-    #
-    #   Connection::STATE.Initialized
-    #   Connection::STATE.Connecting
-    #   Connection::STATE.Connected
-    #   Connection::STATE.Disconnected
-    #   Connection::STATE.Suspended
-    #   Connection::STATE.Closing
-    #   Connection::STATE.Closed
-    #   Connection::STATE.Failed
-    #
-    # @example
-    #    client = Ably::Realtime::Client.new('key.id:secret')
-    #    client.connection.on(:connected) do
-    #      puts "Connected with connection ID: #{client.connection.id}"
-    #    end
-    #
-    # @!attribute [r] state
-    #   @return [Ably::Realtime::Connection::STATE] connection state
+    # Enables the management of a connection to Ably.
     #
     class Connection
       include Ably::Modules::EventEmitter
@@ -42,8 +10,50 @@ module Ably
       include Ably::Modules::SafeYield
       extend Ably::Modules::Enum
 
-      # ConnectionState
-      # The permited states for this connection
+      # The current {Ably::Realtime::Connection::STATE} of the connection.
+      # Describes the realtime [Connection]{@link Connection} object states.
+      #
+      # @spec RTN4d
+      #
+      # INITIALIZED		A connection with this state has been initialized but no connection has yet been attempted.
+      # CONNECTING		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.
+      # CONNECTED		  A connection exists and is active.
+      # DISCONNECTED		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.
+      # SUSPENDED		  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 {Ably::Realtime::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.
+      # CLOSING		  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.
+      # CLOSED		  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 {Ably::Realtime::Connection#connect}, which results in a new connection.
+      # FAILED		  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 {Ably::Realtime::Connection#connect}.
+      #
+      # @return [Ably::Realtime::Connection::STATE]
+      #
       STATE = ruby_enum('STATE',
         :initialized,
         :connecting,
@@ -55,8 +65,10 @@ module Ably
         :failed
       )
 
-      # ConnectionEvent
-      # The permitted connection events that are emitted for this connection
+      # Describes the events emitted by a {Ably::Realtime::Connection} object. An event is either an UPDATE or a {Ably::Realtime::Connection::STATE}.
+      #
+      # UPDATE	RTN4h	An event for changes to connection conditions for which the {Ably::Realtime::Connection::STATE} does not change.
+      #
       EVENT = ruby_enum('EVENT',
         STATE.to_sym_arr + [:update]
       )
@@ -82,20 +94,41 @@ module Ably
       # Max number of messages to bundle in a single ProtocolMessage
       MAX_PROTOCOL_MESSAGE_BATCH_SIZE = 50
 
-      # A unique public identifier for this connection, used to identify this member in presence events and messages
+      # A unique public identifier for this connection, used to identify this member.
+      #
+      # @spec RTN8
+      #
       # @return [String]
+      #
       attr_reader :id
 
-      # A unique private connection key used to recover this connection, assigned by Ably
+      # 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 for more info.
+      #
+      # @spec RTN9
+      #
       # @return [String]
+      #
       attr_reader :key
 
-      # The serial number of the last message to be received on this connection, used to recover or resume a connection
+      # 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.
+      #
+      # @spec RTN10
+      #
       # @return [Integer]
+      #
       attr_reader :serial
 
-      # When a connection failure occurs this attribute contains the Ably Exception
+      # An {Ably::Models::ErrorInfo} object describing the last error received if a connection failure occurs.
+      #
+      # @spec RTN14a
+      #
       # @return [Ably::Models::ErrorInfo,Ably::Exceptions::BaseAblyException]
+      #
       attr_reader :error_reason
 
       # Connection details of the currently established connection
@@ -165,9 +198,11 @@ module Ably
         @current_host = client.endpoint.host
       end
 
-      # Causes the connection to close, entering the closed state, from any state except
-      # the failed state. Once closed, the library will not attempt to re-establish the
-      # connection without a call to {Connection#connect}.
+      # Causes the connection to close, entering the {Ably::Realtime::Connection::STATE} CLOSING state.
+      # Once closed, the library does not attempt to re-establish the connection without an explicit call to
+      # {Ably::Realtime::Connection#connect}.
+      #
+      # @spec RTN12
       #
       # @yield block is called as soon as this connection is in the Closed state
       #
@@ -183,13 +218,11 @@ module Ably
         deferrable_for_state_change_to(STATE.Closed, &success_block)
       end
 
-      # Causes the library to attempt connection.  If it was previously explicitly
-      # closed by the user, or was closed as a result of an unrecoverable error, a new connection will be opened.
-      # Succeeds when connection is established i.e. state is @Connected@
-      # Fails when state becomes either @Closing@, @Closed@ or @Failed@
+      # Explicitly calling connect() is unnecessary unless the autoConnect attribute of
+      # the ClientOptions object is false. Unless already connected or connecting,
+      # this method causes the connection to open, entering the {Ably::Realtime::Connection::STATE} CONNECTING state.
       #
-      # Note that if the connection remains in the disconnected ans suspended states indefinitely,
-      # the Deferrable or block provided may never be called
+      # @spec RTC1b, RTN3, RTN11
       #
       # @yield block is called as soon as this connection is in the Connected state
       #
@@ -223,9 +256,11 @@ module Ably
         end
       end
 
-      # Sends a ping to Ably and yields the provided block when a heartbeat ping request is echoed from the server.
-      # This can be useful for measuring true roundtrip client to Ably server latency for a simple message, or checking that an underlying transport is responding currently.
-      # The elapsed time in seconds is passed as an argument to the block and represents the time taken to echo a ping heartbeat once the connection is in the `:connected` state.
+      # When connected, sends a heartbeat ping to the Ably server and executes the callback with any error
+      # and the response time in milliseconds when a heartbeat ping request is echoed from the server.
+      # This can be useful for measuring true round-trip latency to the connected Ably server.
+      #
+      # @spec RTN13
       #
       # @yield [Integer] if a block is passed to this method, then this block will be called once the ping heartbeat is received with the time elapsed in seconds.
       #                  If the ping is not received within an acceptable timeframe, the block will be called with +nil+ as he first argument
@@ -312,8 +347,12 @@ module Ably
         end
       end
 
-      # @!attribute [r] recovery_key
-      # @return [String] recovery key that can be used by another client to recover this connection with the :recover option
+      # 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 for more information.
+      #
+      # @spec RTN16b, RTN16c
+      #
+      # @return [String]
+      #
       def recovery_key
         "#{key}:#{serial}:#{client_msg_serial}" if connection_resumable?
       end

data/lib/ably/realtime/presence.rb

@@ -1,5 +1,6 @@
 module Ably::Realtime
-  # Presence provides access to presence operations and state for the associated Channel
+  # Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel.
+  #
   class Presence
     include Ably::Modules::Conversions
     include Ably::Modules::EventEmitter
@@ -90,15 +91,14 @@ module Ably::Realtime
       end
     end
 
-    # Enter the specified client_id into this channel. The given client will be added to the
-    # presence set and presence subscribers will see a corresponding presence message.
-    # This method is provided to support connections (e.g. connections from application
-    # server instances) that act on behalf of multiple client_ids. In order to be able to
-    # enter the channel with this method, the client library must have been instanced
-    # either with a key, or with a token bound to the wildcard client_id
+    # Enters the presence set of the channel for a given clientId. Enables a single client to update presence on behalf
+    # of any number of clients using a single connection. The library must have been instantiated with an API key
+    # or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success or failure of the operation.
+    #
+    # @spec RTP4, RTP14, RTP15
     #
     # @param [String]  client_id   id of the client
-    # @param [String,Hash,nil]   data   optional data (eg a status message) for this member
+    # @param [String,Hash,nil]   data   The payload associated with the presence member. A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads.
     #
     # @yield [Ably::Realtime::Presence] On success, will call the block with this {Ably::Realtime::Presence} object
     # @return [Ably::Util::SafeDeferrable] Deferrable that supports both success (callback) and failure (errback) callbacks
@@ -151,13 +151,16 @@ module Ably::Realtime
       end
     end
 
-    # Leave a given client_id from this channel. This client will be removed from the
-    # presence set and presence subscribers will see a leave message for this client.
+    # Leaves the presence set of the channel for a given clientId. Enables a single client to update presence on behalf
+    # of any number of clients using a single connection. The library must have been instantiated with an API key
+    # or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success or failure of the operation.
     #
-    # @param (see Presence#enter_client)
+    # @spec RTP15
     #
-    # @yield (see Presence#enter_client)
-    # @return (see Presence#enter_client)
+    # @param (see {Ably::Realtime::Presence#enter_client})
+    #
+    # @yield (see {Ably::Realtime::Presence#enter_client})
+    # @return (see {Ably::Realtime::Presence#enter_client})
     #
     def leave_client(client_id, data = nil, &success_block)
       ensure_supported_client_id client_id
@@ -166,14 +169,15 @@ module Ably::Realtime
       send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Leave, client_id, data, &success_block)
     end
 
-    # Update the presence data for this client. If the client is not already a member of
-    # the presence set it will be added, and presence subscribers will see an enter or
-    # update message for this client.
+    # Updates the data payload for a presence member. If called before entering the presence set, this is treated as
+    # an {Ably::Realtime::Presence::STATE.Entered} event. An optional callback may be provided to notify of the success or failure of the operation.
     #
-    # @param (see Presence#enter)
+    # @spec RTP9
     #
-    # @yield (see Presence#enter)
-    # @return (see Presence#enter)
+    # @param (see {Ably::Realtime::Presence#enter})
+    #
+    # @yield (see {Ably::Realtime::Presence#enter})
+    # @return (see {Ably::Realtime::Presence#enter})
     #
     def update(data = nil, &success_block)
       deferrable = create_deferrable
@@ -197,11 +201,12 @@ module Ably::Realtime
       end
     end
 
-    # Update the presence data for a specified client_id into this channel.
-    # If the client is not already a member of the presence set it will be added, and
-    # presence subscribers will see an enter or update message for this client.
-    # As with {#enter_client}, the connection must be authenticated in a way that
-    # enables it to represent an arbitrary clientId.
+    # Updates the data payload for a presence member using a given clientId. Enables a single client to update presence
+    # on behalf of any number of clients using a single connection. The library must have been instantiated with an API
+    # key or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success
+    # or failure of the operation.
+    #
+    # @spec RTP15
     #
     # @param (see Presence#enter_client)
     #
@@ -215,12 +220,16 @@ module Ably::Realtime
       send_presence_action_for_client(Ably::Models::PresenceMessage::ACTION.Update, client_id, data, &success_block)
     end
 
-    # Get the presence members for this Channel.
+    # Retrieves the current members present on the channel and the metadata for each member, such as their
+    # {Ably::Models::ProtocolMessage::ACTION} and ID. Returns an array of {Ably::Models::PresenceMessage} objects.
+    #
+    # @spec RTP11, RTP11c1, RTP11c2, RTP11c3
+    #
+    # @param (see {Ably::Realtime::Presence::MembersMap#get})
+    # @option options (see {Ably::Realtime::Presence::MembersMap#get})
+    # @yield (see {Ably::Realtime::Presence::MembersMap#get})
     #
-    # @param (see Ably::Realtime::Presence::MembersMap#get)
-    # @option options (see Ably::Realtime::Presence::MembersMap#get)
-    # @yield (see Ably::Realtime::Presence::MembersMap#get)
-    # @return (see Ably::Realtime::Presence::MembersMap#get)
+    # @return (see {Ably::Realtime::Presence::MembersMap#get})
     #
     def get(options = {}, &block)
       deferrable = create_deferrable
@@ -252,8 +261,11 @@ module Ably::Realtime
       end
     end
 
-    # Subscribe to presence events on the associated Channel.
-    # This implicitly attaches the Channel if it is not already attached.
+    # Registers a listener that is called each time a {Ably::Models::PresenceMessage} is received on the channel,
+    # such as a new member entering the presence set. A callback may optionally be passed in to this call to be notified
+    # of success or failure of the channel {Ably::Realtime::Channel#attach} operation.
+    #
+    # @spec RTP6a, RTP6b
     #
     # @param actions [Ably::Models::PresenceMessage::ACTION] Optional, the state change action to subscribe to. Defaults to all presence actions
     # @yield [Ably::Models::PresenceMessage] For each presence state change event, the block is called
@@ -266,7 +278,9 @@ module Ably::Realtime
     end
 
     # Unsubscribe the matching block for presence events on the associated Channel.
-    # If a block is not provided, all subscriptions will be unsubscribed
+    # If a block is not provided, all subscriptions will be unsubscribed {Ably::Models::PresenceMessage} for the channel.
+    #
+    # @spec RTP7a, RTP7b, RTE5
     #
     # @param actions [Ably::Models::PresenceMessage::ACTION] Optional, the state change action to subscribe to. Defaults to all presence actions
     #
@@ -276,10 +290,15 @@ module Ably::Realtime
       super
     end
 
-    # Return the presence messages history for the channel
+    # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical
+    # {Ably::Models::PresenceMessage} objects for the channel. If the channel is configured to persist messages,
+    # then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages
+    # can only be retrieved from history for up to two minutes in the past.
     #
-    # @param (see Ably::Rest::Presence#history)
-    # @option options (see Ably::Rest::Presence#history)
+    # @spec RTP12c, RTP12a
+    #
+    # @param (see {Ably::Rest::Presence#history})
+    # @option options (see {Ably::Rest::Presence#history})
     #
     # @yield [Ably::Models::PaginatedResult<Ably::Models::PresenceMessage>] First {Ably::Models::PaginatedResult page} of {Ably::Models::PresenceMessage} objects accessible with {Ably::Models::PaginatedResult#items #items}.
     #
@@ -306,7 +325,13 @@ module Ably::Realtime
       client.logger
     end
 
-    # Returns true when the initial member SYNC following channel attach is completed
+    # Indicates whether the presence set synchronization between Ably and the clients on the channel has been completed.
+    # Set to true when the sync is complete.
+    #
+    # @spec RTP13
+    #
+    # return [Boolean]
+    #
     def sync_complete?
       members.sync_complete?
     end

data/lib/ably/realtime/push/admin.rb

@@ -5,6 +5,7 @@ module Ably::Realtime
   class Push
     # Class providing push notification administrative functionality
     # for registering devices and attaching to channels etc.
+    #
     class Admin
       include Ably::Modules::AsyncWrapper
       include Ably::Modules::Conversions
@@ -20,9 +21,14 @@ module Ably::Realtime
         @client = push.client
       end
 
+      # Sends a push notification directly to a device, or a group of devices sharing the same clientId.
+      #
       # (see Ably::Rest::Push#publish)
       #
+      # @spec RSH1a
+      #
       # @yield  Block is invoked upon successful publish of the message
+      #
       # @return [Ably::Util::SafeDeferrable]
       #
       def publish(recipient, data, &callback)
@@ -36,14 +42,22 @@ module Ably::Realtime
         end
       end
 
-      # Manage device registrations
+      # A {Ably::Realtime::Push::DeviceRegistrations} object.
+      #
+      # @spec RSH1b
+      #
       # @return [Ably::Realtime::Push::DeviceRegistrations]
+      #
       def device_registrations
         @device_registrations ||= DeviceRegistrations.new(self)
       end
 
-      # Manage channel subscriptions for devices or clients
+      # A {Ably::Realtime::Push::ChannelSubscriptions} object.
+      #
+      # @spec RSH1c
+      #
       # @return [Ably::Realtime::Push::ChannelSubscriptions]
+      #
       def channel_subscriptions
         @channel_subscriptions ||= ChannelSubscriptions.new(self)
       end

data/lib/ably/realtime/push.rb

@@ -11,27 +11,39 @@ module Ably
         @client = client
       end
 
-      # Admin features for push notifications like managing devices and channel subscriptions
+      # A {Ably::Realtime::Push::Admin} object.
+      #
+      # @spec RSH1
+      #
       # @return [Ably::Realtime::Push::Admin]
+      #
       def admin
         @admin ||= Admin.new(self)
       end
 
-      # Activate this device for push notifications by registering with the push transport such as GCM/APNS
+      # Activates the device for push notifications with FCM or APNS, obtaining a unique identifier from them.
+      # Subsequently registers the device with Ably and stores the deviceIdentityToken in local storage.
+      #
+      # @spec RSH2a
       #
       # @note This is unsupported in the Ruby library
+      #
       def activate(*arg)
         raise_unsupported
       end
 
-      # Deactivate this device for push notifications by removing the registration with the push transport such as GCM/APNS
+      # Deactivates the device from receiving push notifications with Ably and FCM or APNS.
+      #
+      # @spec RSH2b
       #
       # @note This is unsupported in the Ruby library
+      #
       def deactivate(*arg)
         raise_unsupported
       end
 
       private
+
       def raise_unsupported
         raise Ably::Exceptions::PushNotificationsNotSupported, 'This device does not support receiving or subscribing to push notifications. All PushChannel methods are unavailable'
       end

data/lib/ably/rest/channel/push_channel.rb

@@ -3,9 +3,6 @@ module Ably::Rest
     # A push channel used for push notifications
     # Each PushChannel maps to exactly one Rest Channel
     #
-    # @!attribute [r] channel
-    #   @return [Ably::Rest::Channel] Underlying channel object
-    #
     class PushChannel
       attr_reader :channel
 

data/lib/ably/rest/channel.rb

@@ -1,12 +1,7 @@
 module Ably
   module Rest
-    # The Ably Realtime service organises the traffic within any application into named channels.
-    # Channels are the "unit" of message distribution; clients attach to channels to subscribe to messages, and every message broadcast by the service is associated with a unique channel.
+    # Enables messages to be published and historic messages to be retrieved for a channel.
     #
-    # @!attribute [r] name
-    #   @return {String} channel name
-    # @!attribute [r] options
-    #   @return {Hash} channel options configured for this channel, see {#initialize} for channel_options
     class Channel
       include Ably::Modules::Conversions
 
@@ -15,9 +10,14 @@ module Ably
       # @api private
       attr_reader :client
 
-      attr_reader :name, :options
+      # The channel name.
+      # @return [String]
+      attr_reader :name
 
-      # Push channel used for push notification (client-side)
+      attr_reader :options
+
+      # A {Ably::Rest::Channel::PushChannel} object
+      # @spec RSH4
       # @return [Ably::Rest::Channel::PushChannel]
       # @api private
       attr_reader :push
@@ -39,7 +39,10 @@ module Ably
         @push    = PushChannel.new(self)
       end
 
-      # Publish one or more messages to the channel. Five overloaded forms
+      # Publishes a message to the channel. A callback may optionally be passed in to this call to be notified of success or failure of the operation.
+      #
+      # @spec RSL1
+      #
       # @param name [String, Array<Ably::Models::Message|Hash>, Ably::Models::Message, nil]   The event name of the message to publish, or an Array of [Ably::Model::Message] objects or [Hash] objects with +:name+ and +:data+ pairs, or a single Ably::Model::Message object
       # @param data [String, Array, Hash, nil]   The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument, in which case an optional hash of query parameters
       # @param attributes [Hash, nil]   Optional additional message attributes such as :extras, :id, :client_id or :connection_id, applied when name attribute is nil or a string (Deprecated, will be removed in 2.0 in favour of constructing a Message object)
@@ -112,15 +115,19 @@ module Ably
         [201, 204].include?(response.status)
       end
 
-      # Return the message   of the channel
+      # Retrieves a {Ably::Models::PaginatedResult} object, containing an array of historical {Ably::Models::Message}
+      # objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from
+      # history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past.
+      #
+      # @spec RSL2a
       #
       # @param [Hash] options   the options for the message history request
-      # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any messages retrieved is +:start+
-      # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any messages retrieved is +:end+
-      # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
-      # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
+      # @option options [Integer,Time] :start      The time from which messages are retrieved, specified as milliseconds since the Unix epoch. RSL2b1
+      # @option options [Integer,Time] :end        The time until messages are retrieved, specified as milliseconds since the Unix epoch. RSL2b1
+      # @option options [Symbol]       :direction  The order for which messages are returned in. Valid values are backwards which orders messages from most recent to oldest, or forwards which orders messages from oldest to most recent. The default is backwards. RSL2b2
+      # @option options [Integer]      :limit      An upper limit on the number of messages returned. The default is 100, and the maximum is 1000. RSL2b3
       #
-      # @return [Ably::Models::PaginatedResult<Ably::Models::Message>] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}.
+      # @return [Ably::Models::PaginatedResult<Ably::Models::Message>] A {Ably::Models::PaginatedResult} object containing an array of {Ably::Models::Message} objects.
       #
       def history(options = {})
         url = "#{base_path}/messages"
@@ -146,14 +153,15 @@ module Ably
         end
       end
 
-      # Return the {Ably::Rest::Presence} object
-      #
+      # A {Ably::Rest::Presence} object.
+      # @spec RSL3
       # @return [Ably::Rest::Presence]
       def presence
         @presence ||= Presence.new(client, self)
       end
 
-      # Sets or updates the stored channel options. (#RSL7)
+      # Sets the {Ably::Models::ChannelOptions} for the channel.
+      # @spec RSL7
       # @param channel_options [Hash, Ably::Models::ChannelOptions]  A hash of options or a {Ably::Models::ChannelOptions}
       # @return [Ably::Models::ChannelOptions]
       def set_options(channel_options)
@@ -161,9 +169,9 @@ module Ably
       end
       alias options= set_options
 
-      # Makes GET request for channel details (#RSL8, #RSL8a)
-      #
-      # @return [Ably::Models::ChannelDetails]
+      # Retrieves a {Ably::Models::ChannelDetails} object for the channel, which includes status and occupancy metrics.
+      # @spec RSL8
+      # @return [Ably::Models::ChannelDetails] 	A {Ably::Models::ChannelDetails} object.
       def status
         Ably::Models::ChannelDetails.new(client.get(base_path).body)
       end

data/lib/ably/rest/channels.rb

@@ -8,24 +8,26 @@ module Ably
         super client, Ably::Rest::Channel
       end
 
-      # @!method get(name, channel_options = {})
       # Return a {Ably::Rest::Channel} for the given name
       #
       # @param name [String] The name of the channel
       # @param channel_options [Hash] Channel options, currently reserved for Encryption options
-      # @return [Ably::Rest::Channel}
+      #
+      # @return [Ably::Rest::Channel]
+      #
       def get(*args)
         super
       end
 
-      # @!method fetch(name, &missing_block)
       # Return a {Ably::Rest::Channel} for the given name if it exists, else the block will be called.
       # This method is intentionally similar to {http://ruby-doc.org/core-2.1.3/Hash.html#method-i-fetch Hash#fetch} providing a simple way to check if a channel exists or not without creating one
       #
       # @param name [String] The name of the channel
       # @yield [options] (optional) if a missing_block is passed to this method and no channel exists matching the name, this block is called
       # @yieldparam [String] name of the missing channel
+      #
       # @return [Ably::Rest::Channel]
+      #
       def fetch(*args)
         super
       end
@@ -36,6 +38,7 @@ module Ably
       # {Ably::Rest::Channel} object. Explicitly release channels to free up resources if required
       #
       # @return [void]
+      #
       def release(*args)
         super
       end