ably 1.2.2 → 1.2.4

data/lib/ably/realtime/client.rb

@@ -3,22 +3,7 @@ require 'ably/realtime/channel/publisher'
 
 module Ably
   module Realtime
-    # Client for the Ably Realtime API
-    #
-    # @!attribute [r] client_id
-    #   (see Ably::Rest::Client#client_id)
-    # @!attribute [r] auth_options
-    #   (see Ably::Rest::Client#auth_options)
-    # @!attribute [r] environment
-    #   (see Ably::Rest::Client#environment)
-    # @!attribute [r] channels
-    #   @return [Aby::Realtime::Channels] The collection of {Ably::Realtime::Channel}s that have been created
-    # @!attribute [r] encoders
-    #   (see Ably::Rest::Client#encoders)
-    # @!attribute [r] protocol
-    #   (see Ably::Rest::Client#protocol)
-    # @!attribute [r] protocol_binary?
-    #   (see Ably::Rest::Client#protocol_binary?)
+    # A client that extends the functionality of the {Ably::Realtime::Client} and provides additional realtime-specific features.
     #
     class Client
       include Ably::Modules::AsyncWrapper
@@ -29,19 +14,33 @@ module Ably
 
       DOMAIN = 'realtime.ably.io'
 
-      # The collection of {Ably::Realtime::Channel}s that have been created
+      # A {Aby::Realtime::Channels} object.
+      #
+      # @spec RTC3, RTS1
+      #
       # @return [Aby::Realtime::Channels]
+      #
       attr_reader :channels
 
-      # (see Ably::Rest::Client#auth)
+      # An {Ably::Auth} object.
+      #
+      # @spec RTC4
+      #
+      # @return [Ably::Auth]
+      #
       attr_reader :auth
 
-      # The underlying connection for this client
+      # A {Aby::Realtime::Connection} object.
+      #
+      # @spec RTC2
+      #
       # @return [Aby::Realtime::Connection]
+      #
       attr_reader :connection
 
       # The {Ably::Rest::Client REST client} instantiated with the same credentials and configuration that is used for all REST operations such as authentication
       # @return [Ably::Rest::Client]
+
       # @private
       attr_reader :rest_client
 
@@ -78,8 +77,10 @@ module Ably
 
       # Creates a {Ably::Realtime::Client Realtime Client} and configures the {Ably::Auth} object for the connection.
       #
-      # @param (see Ably::Rest::Client#initialize)
-      # @option options (see Ably::Rest::Client#initialize)
+      # @spec RSC1
+      #
+      # @param (see {Ably::Rest::Client#initialize})
+      # @option options (see Ably::Rest::Client#initialize) An options {Hash} object.
       # @option options [Proc]                    :auth_callback       when provided, the Proc will be called with the token params hash as the first argument, whenever a new token is required.
       #                                                                Whilst the proc is called synchronously, it does not block the EventMachine reactor as it is run in a separate thread.
       #                                                                The Proc should return a token string, {Ably::Models::TokenDetails} or JSON equivalent, {Ably::Models::TokenRequest} or JSON equivalent
@@ -97,10 +98,10 @@ module Ably
       # @return [Ably::Realtime::Client]
       #
       # @example
-      #    # create a new client authenticating with basic auth
+      #    # Constructs a {Ably::Realtime::Client} object using an Ably API key or token string.
       #    client = Ably::Realtime::Client.new('key.id:secret')
       #
-      #    # create a new client and configure a client ID used for presence
+      #    # Constructs a {Ably::Realtime::Client} object using an Ably options object.
       #    client = Ably::Realtime::Client.new(key: 'key.id:secret', client_id: 'john')
       #
       def initialize(options)
@@ -141,9 +142,13 @@ module Ably
         channels.get(name, channel_options)
       end
 
-      # Retrieve the Ably service time
+      # Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access
+      # to a sufficiently well maintained time source and wish to issue Ably {Ably::Models::TokenRequests} with
+      # a more accurate timestamp should use the queryTime property instead of this method.
+      #
+      # @spec RTC6a
       #
-      # @yield [Time] The time as reported by the Ably service
+      # @yield [Time] The time as milliseconds since the Unix epoch.
       # @return [Ably::Util::SafeDeferrable]
       #
       def time(&success_callback)
@@ -152,12 +157,15 @@ module Ably
         end
       end
 
-      # Retrieve the stats for the application
+      # Queries the REST /stats API and retrieves your application's usage statistics.
+      # Returns a {Ably::Util::SafeDeferrable} object, containing an array of {Ably::Models::Stats} objects. See the Stats docs.
+      #
+      # @spec RTC5
       #
       # @param (see Ably::Rest::Client#stats)
       # @option options (see Ably::Rest::Client#stats)
       #
-      # @yield [Ably::Models::PaginatedResult<Ably::Models::Stats>] An Array of Stats
+      # @yield [Ably::Models::PaginatedResult<Ably::Models::Stats>] A {Ably::Util::SafeDeferrable} object containing an array of {Ably::Models::Stats} objects.
       #
       # @return [Ably::Util::SafeDeferrable]
       #
@@ -167,26 +175,38 @@ module Ably
         end
       end
 
+      # Calls {Connection#close} and causes the connection to close, entering the closing state.
+      # Once closed, the library will not attempt to re-establish the connection without an explicit call to {Connection#connect}.
+      # @spec RTN12
       # (see Ably::Realtime::Connection#close)
       def close(&block)
         connection.close(&block)
       end
 
+      # Calls {Ably::Realtime::Connection#connect} and causes the connection to open, entering the connecting
+      # state. Explicitly calling connect() is unnecessary unless the autoConnect property is disabled.
+      # @spec RTN11
       # (see Ably::Realtime::Connection#connect)
       def connect(&block)
         connection.connect(&block)
       end
 
-      # Push notification object for publishing and managing push notifications
+      # A {Ably::Realtime::Push} object.
       # @return [Ably::Realtime::Push]
       def push
         @push ||= Push.new(self)
       end
 
-      # (see Ably::Rest::Client#request)
+      # Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST
+      # API functionality that is either not documented or is not yet included in the public API, without having to
+      # directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support.
+      #
+      # @spec RTC9
+      #
+      # (see {Ably::Rest::Client#request})
       # @yield [Ably::Models::HttpPaginatedResponse<>] An Array of Stats
       #
-      # @return [Ably::Util::SafeDeferrable]
+      # @return [Ably::Util::SafeDeferrable] An {Ably::Util::SafeDeferrable} response object returned by the HTTP request, containing an empty or JSON-encodable object.
       def request(method, path, params = {}, body = nil, headers = {}, &callback)
         async_wrap(callback) do
           rest_client.request(method, path, params, body, headers, async_blocking_operations: true)
@@ -303,8 +323,9 @@ module Ably
         @fallback_endpoints[fallback_endpoint_index % @fallback_endpoints.count]
       end
 
-      # The local device detilas
-      # @return [Ably::Models::LocalDevice]
+      # Retrieves a {Ably::Models::LocalDevice} object that represents the current state of the device as a target for push notifications.
+      # @spec RSH8
+      # @return [Ably::Models::LocalDevice] A {Ably::Models::LocalDevice} object.
       #
       # @note This is unsupported in the Ruby library
       def device

data/lib/ably/realtime/connection/connection_manager.rb

@@ -270,7 +270,9 @@ module Ably::Realtime
       end
 
       # Number of consecutive attempts for provided state
+      #
       # @return [Integer]
+      #
       # @api private
       def retry_count_for_state(state)
         retries_for_state(state, ignore_states: [:connecting]).count
@@ -356,7 +358,9 @@ module Ably::Realtime
       end
 
       # Timers used to manage connection state, for internal use by the client library
+      #
       # @return [Hash]
+      #
       def timers
         @timers
       end

data/lib/ably/realtime/connection/websocket_transport.rb

@@ -31,7 +31,9 @@ module Ably::Realtime
 
       # Disconnect the socket transport connection and write all pending text.
       # If Disconnected state is not automatically emitted, it will be emitted automatically
+      #
       # @return [void]
+      #
       # @api public
       def disconnect
         close_connection_after_writing
@@ -133,15 +135,15 @@ module Ably::Realtime
         !connecting? && !connected?
       end
 
-      # @!attribute [r] __incoming_protocol_msgbus__
       # @return [Ably::Util::PubSub] Websocket Transport internal incoming protocol message bus
+      #
       # @api private
       def __incoming_protocol_msgbus__
         @__incoming_protocol_msgbus__ ||= create_pub_sub_message_bus
       end
 
-      # @!attribute [r] __outgoing_protocol_msgbus__
       # @return [Ably::Util::PubSub] Websocket Transport internal outgoing protocol message bus
+      #
       # @api private
       def __outgoing_protocol_msgbus__
         @__outgoing_protocol_msgbus__ ||= create_pub_sub_message_bus

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