Full Action Cable documentation read through

This PR checks all active Action Cable documentation for typos and other
fixes. It aims to make sure that when Rails 5 is released, that the
Action Cable docs are up to snuff with the other documentation included
with Rails.

[ci skip]

2 files changed, 17 insertions, 17 deletions

diff --git a/actioncable/lib/action_cable/channel/base.rb b/actioncable/lib/action_cable/channel/base.rb
index 874ebe2e71..1be2182bc1 100644
--- a/actioncable/lib/action_cable/channel/base.rb
+++ b/actioncable/lib/action_cable/channel/base.rb
@@ -32,8 +32,8 @@ module ActionCable
     #
     # == Action processing
     #
-    # Unlike subclasses of ActionController::Base, channels do not follow a REST
-    # constraint form for their actions. Instead, ActionCable operates through a
+    # Unlike subclasses of ActionController::Base, channels do not follow a RESTful
+    # constraint form for their actions. Instead, Action Cable operates through a
     # remote-procedure call model. You can declare any public method on the
     # channel (optionally taking a <tt>data</tt> argument), and this method is
     # automatically exposed as callable to the client.
@@ -63,10 +63,10 @@ module ActionCable
     #       end
     #   end
     #
-    # In this example, subscribed/unsubscribed are not callable methods, as they
+    # In this example, the subscribed and unsubscribed methods are not callable methods, as they
     # were already declared in ActionCable::Channel::Base, but <tt>#appear</tt>
     # and <tt>#away</tt> are. <tt>#generate_connection_token</tt> is also not
-    # callable as it's a private method. You'll see that appear accepts a data
+    # callable, since it's a private method. You'll see that appear accepts a data
     # parameter, which it then uses as part of its model call. <tt>#away</tt>
     # does not, since it's simply a trigger action.
     #
@@ -125,7 +125,7 @@ module ActionCable
         protected
           # action_methods are cached and there is sometimes need to refresh
           # them. ::clear_action_methods! allows you to do that, so next time
-          # you run action_methods, they will be recalculated
+          # you run action_methods, they will be recalculated.
           def clear_action_methods!
             @action_methods = nil
           end
@@ -166,9 +166,9 @@ module ActionCable
         end
       end
 
-      # Called by the cable connection when its cut so the channel has a chance to cleanup with callbacks.
+      # Called by the cable connection when its cut, so the channel has a chance to cleanup with callbacks.
       # This method is not intended to be called directly by the user. Instead, overwrite the #unsubscribed callback.
-      def unsubscribe_from_channel
+      def unsubscribe_from_channel # :nodoc:
         run_callbacks :unsubscribe do
           unsubscribed
         end
@@ -183,7 +183,7 @@ module ActionCable
         end
 
         # Called once a consumer has cut its cable connection. Can be used for cleaning up connections or marking
-        # people as offline or the like.
+        # users as offline or the like.
         def unsubscribed
           # Override in subclasses
         end
@@ -224,7 +224,6 @@ module ActionCable
           end
         end
 
-
         def subscribe_to_channel
           run_callbacks :subscribe do
             subscribed
@@ -237,7 +236,6 @@ module ActionCable
           end
         end
 
-
         def extract_action(data)
           (data['action'].presence || :receive).to_sym
         end
diff --git a/actioncable/lib/action_cable/channel/streams.rb b/actioncable/lib/action_cable/channel/streams.rb
index 3158f30814..3e3be4cd44 100644
--- a/actioncable/lib/action_cable/channel/streams.rb
+++ b/actioncable/lib/action_cable/channel/streams.rb
@@ -1,8 +1,8 @@
 module ActionCable
   module Channel
     # Streams allow channels to route broadcastings to the subscriber. A broadcasting is, as discussed elsewhere, a pub/sub queue where any data
-    # put into it is automatically sent to the clients that are connected at that time. It's purely an online queue, though. If you're not
-    # streaming a broadcasting at the very moment it sends out an update, you'll not get that update when connecting later.
+    # placed into it is automatically sent to the clients that are connected at that time. It's purely an online queue, though. If you're not
+    # streaming a broadcasting at the very moment it sends out an update, you will not get that update, if you connect after it has been sent.
     #
     # Most commonly, the streamed broadcast is sent straight to the subscriber on the client-side. The channel just acts as a connector between
     # the two parties (the broadcaster and the channel subscriber). Here's an example of a channel that allows subscribers to get all new
@@ -18,8 +18,10 @@ module ActionCable
     #     end
     #   end
     #
-    # So the subscribers of this channel will get whatever data is put into the, let's say, `comments_for_45` broadcasting as soon as it's put there.
-    # That looks like so from that side of things:
+    # Based on the above example, the subscribers of this channel will get whatever data is put into the,
+    # let's say, `comments_for_45` broadcasting as soon as it's put there.
+    #
+    # An example broadcasting for this channel looks like so:
     #
     #   ActionCable.server.broadcast "comments_for_45", author: 'DHH', content: 'Rails is just swell'
     #
@@ -37,8 +39,8 @@ module ActionCable
     #
     #   CommentsChannel.broadcast_to(@post, @comment)
     #
-    # If you don't just want to parlay the broadcast unfiltered to the subscriber, you can supply a callback that lets you alter what goes out.
-    # Example below shows how you can use this to provide performance introspection in the process:
+    # If you don't just want to parlay the broadcast unfiltered to the subscriber, you can also supply a callback that lets you alter what is sent out.
+    # The below example shows how you can use this to provide performance introspection in the process:
     #
     #   class ChatChannel < ApplicationCable::Channel
     #     def subscribed
@@ -70,7 +72,7 @@ module ActionCable
       # Start streaming from the named <tt>broadcasting</tt> pubsub queue. Optionally, you can pass a <tt>callback</tt> that'll be used
       # instead of the default of just transmitting the updates straight to the subscriber.
       def stream_from(broadcasting, callback = nil)
-        # Hold off the confirmation until pubsub#subscribe is successful
+        # Don't send the confirmation until pubsub#subscribe is successful
         defer_subscription_confirmation!
 
         callback ||= default_stream_callback(broadcasting)