channel.rb in ably-0.8.0

- old
+ new

@@ -98,12 +98,14 @@
 
         setup_event_handlers
         setup_presence
       end
 
-      # Publish a message on the channel
+      # Publish a message on the channel.
       #
+      # When publishing a message, if the channel is not attached, the channel is implicitly attached
+      #
       # @param name [String] The event name of the message
       # @param data [String,ByteArray] payload for the message
       # @yield [Ably::Models::Message] On success, will call the block with the {Ably::Models::Message}
       # @return [Ably::Models::Message] Deferrable {Ably::Models::Message} that supports both success (callback) and failure (errback) callbacks
       #
@@ -125,12 +127,14 @@
           message.callback(&success_block) if block_given?
           queue_message message
         end
       end
 
-      # Subscribe to messages matching providing event name, or all messages if event name not provided
+      # Subscribe to messages matching providing event name, or all messages if event name not provided.
       #
+      # When subscribing to messages, if the channel is not attached, the channel is implicitly attached
+      #
       # @param names [String] The event name of the message to subscribe to if provided.  Defaults to all events.
       # @yield [Ably::Models::Message] For each message received, the block is called
       #
       # @return [void]
       #
@@ -175,33 +179,35 @@
 
       # Presence object for this Channel.  This controls this client's
       # presence on the channel and may also be used to obtain presence information
       # and change events for other members of the channel.
       #
+      # When accessing presence, if the channel is not attached, the channel is implicitly attached
+      #
       # @return {Ably::Realtime::Presence}
       #
       def presence
         attach if initialized?
         @presence
       end
 
       # Return the message history of the channel
       #
-      # Once attached to a channel, you can retrieve messages published on the channel before the
-      # channel was attached with the option <tt>until_attach: true</tt>.  This is very useful for
-      # developers who wish to subscribe to new realtime messages yet also display historical messages with
-      # the guarantee that no messages have been missed.
+      # If the channel is attached, you can retrieve messages published on the channel before the
+      # channel was attached with the option <tt>until_attach: true</tt>.  This is useful when a developer
+      # wishes to display historical messages with the guarantee that no messages have been missed since attach.
       #
       # @param (see Ably::Rest::Channel#history)
       # @option options (see Ably::Rest::Channel#history)
-      # @option options [Boolean]  :until_attach  When true, request for history will be limited only to messages published before this channel was attached. Channel must be attached.
+      # @option options [Boolean]  :until_attach  When true, the history request will be limited only to messages published before this channel was attached. Channel must be attached
       #
       # @yield [Ably::Models::PaginatedResource<Ably::Models::Message>] First {Ably::Models::PaginatedResource page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResource#items #items}.
       #
       # @return [Ably::Util::SafeDeferrable]
+      #
       def history(options = {}, &callback)
         if options.delete(:until_attach)
-          raise ArgumentError, 'option :until_attach cannot be specified if the channel is not attached' unless attached?
+          raise ArgumentError, 'option :until_attach is invalid as the channel is not attached' unless attached?
           options[:from_serial] = attached_serial
         end
 
         async_wrap(callback) do
           rest_channel.history(options.merge(async_blocking_operations: true))