Merge pull request #23668 from maclover7/cable-docs

Full Action Cable documentation read through

4 files changed, 14 insertions, 15 deletions

diff --git a/actioncable/lib/action_cable/connection/base.rb b/actioncable/lib/action_cable/connection/base.rb
index 1acef93025..06706860c2 100644
--- a/actioncable/lib/action_cable/connection/base.rb
+++ b/actioncable/lib/action_cable/connection/base.rb
@@ -2,9 +2,9 @@ require 'action_dispatch'
 
 module ActionCable
   module Connection
-    # For every WebSocket the cable server is accepting, a Connection object will be instantiated. This instance becomes the parent
-    # of all the channel subscriptions that are created from there on. Incoming messages are then routed to these channel subscriptions
-    # based on an identifier sent by the cable consumer. The Connection itself does not deal with any specific application logic beyond
+    # For every WebSocket the Action Cable server accepts, a Connection object will be instantiated. This instance becomes the parent
+    # of all of the channel subscriptions that are created from there on. Incoming messages are then routed to these channel subscriptions
+    # based on an identifier sent by the Action Cable consumer. The Connection itself does not deal with any specific application logic beyond
     # authentication and authorization.
     #
     # Here's a basic example:
@@ -33,8 +33,8 @@ module ActionCable
     #     end
     #   end
     #
-    # First, we declare that this connection can be identified by its current_user. This allows us later to be able to find all connections
-    # established for that current_user (and potentially disconnect them if the user was removed from an account). You can declare as many
+    # First, we declare that this connection can be identified by its current_user. This allows us to later be able to find all connections
+    # established for that current_user (and potentially disconnect them). You can declare as many
     # identification indexes as you like. Declaring an identification means that an attr_accessor is automatically set for that key.
     #
     # Second, we rely on the fact that the WebSocket connection is established with the cookies from the domain being sent along. This makes
@@ -65,8 +65,8 @@ module ActionCable
       end
 
       # Called by the server when a new WebSocket connection is established. This configures the callbacks intended for overwriting by the user.
-      # This method should not be called directly. Rely on the #connect (and #disconnect) callback instead.
-      def process
+      # This method should not be called directly -- instead rely upon on the #connect (and #disconnect) callbacks.
+      def process # :nodoc:
         logger.info started_request_message
 
         if websocket.possible? && allow_request_origin?
@@ -76,7 +76,7 @@ module ActionCable
         end
       end
 
-      # Data received over the cable is handled by this method. It's expected that everything inbound is JSON encoded.
+      # Data received over the WebSocket connection is handled by this method. It's expected that everything inbound is JSON encoded.
       # The data is routed to the proper channel that the connection has subscribed to.
       def receive(data_in_json)
         if websocket.alive?
@@ -88,7 +88,7 @@ module ActionCable
 
       # Send raw data straight back down the WebSocket. This is not intended to be called directly. Use the #transmit available on the
       # Channel instead, as that'll automatically address the correct subscriber and wrap the message in JSON.
-      def transmit(data)
+      def transmit(data) # :nodoc:
         websocket.transmit data
       end
 
diff --git a/actioncable/lib/action_cable/connection/identification.rb b/actioncable/lib/action_cable/connection/identification.rb
index 885ff3f102..4a54044aff 100644
--- a/actioncable/lib/action_cable/connection/identification.rb
+++ b/actioncable/lib/action_cable/connection/identification.rb
@@ -12,7 +12,7 @@ module ActionCable
 
       class_methods do
         # Mark a key as being a connection identifier index that can then be used to find the specific connection again later.
-        # Common identifiers are current_user and current_account, but could be anything really.
+        # Common identifiers are current_user and current_account, but could be anything, really.
         #
         # Note that anything marked as an identifier will automatically create a delegate by the same name on any
         # channel instances created off the connection.
diff --git a/actioncable/lib/action_cable/connection/message_buffer.rb b/actioncable/lib/action_cable/connection/message_buffer.rb
index 2f65a1e84a..19f2e6e918 100644
--- a/actioncable/lib/action_cable/connection/message_buffer.rb
+++ b/actioncable/lib/action_cable/connection/message_buffer.rb
@@ -1,8 +1,7 @@
 module ActionCable
   module Connection
-    # Allows us to buffer messages received from the WebSocket before the Connection has been fully initialized and is ready to receive them.
-    # Entirely internal operation and should not be used directly by the user.
-    class MessageBuffer
+    # Allows us to buffer messages received from the WebSocket before the Connection has been fully initialized, and is ready to receive them.
+    class MessageBuffer # :nodoc:
       def initialize(connection)
         @connection = connection
         @buffered_messages = []
diff --git a/actioncable/lib/action_cable/connection/subscriptions.rb b/actioncable/lib/action_cable/connection/subscriptions.rb
index 24934e12f2..3742f248d1 100644
--- a/actioncable/lib/action_cable/connection/subscriptions.rb
+++ b/actioncable/lib/action_cable/connection/subscriptions.rb
@@ -3,8 +3,8 @@ require 'active_support/core_ext/hash/indifferent_access'
 module ActionCable
   module Connection
     # Collection class for all the channel subscriptions established on a given connection. Responsible for routing incoming commands that arrive on
-    # the connection to the proper channel. Should not be used directly by the user.
-    class Subscriptions
+    # the connection to the proper channel.
+    class Subscriptions # :nodoc:
       def initialize(connection)
         @connection = connection
         @subscriptions = {}