1 files changed, 26 insertions, 0 deletions
diff --git a/lib/action_cable/channel/base.rb b/lib/action_cable/channel/base.rb
index 8e5a4e9cbc..fd510b2597 100644
--- a/lib/action_cable/channel/base.rb
+++ b/lib/action_cable/channel/base.rb
@@ -1,5 +1,31 @@
 module ActionCable
   module Channel
+    # The channel provides the basic structure of grouping behavior into logical units when communicating over the websocket connection.
+    # You can think of a channel like a form of controller, but one that's capable of pushing content to the subscriber in addition to simply
+    # responding to the subscriber's direct requests.
+    #
+    # Channel instances are long-lived. A channel object will be instantiated when the cable consumer becomes a subscriber, and then
+    # lives until the consumer disconnects. This may be seconds, minutes, hours, or even days. That means you have to take special care
+    # not to do anything silly in a channel that would balloon its memory footprint or whatever. The references are forever, so they won't be released
+    # as is normally the case with a controller instance that gets thrown away after every request.
+    #
+    # The upside of long-lived channel instances is that you can use instance variables to keep reference to objects that future subscriber requests
+    # can interact with. Here's a quick example:
+    #
+    #   class ChatChannel < ApplicationChannel
+    #     def subscribed
+    #       @room = Chat::Room[params[:room_number]]
+    #     end
+    #
+    #     def speak(data)
+    #       @room.speak data, user: current_user
+    #     end
+    #   end
+    #
+    # The #speak action simply uses the Chat::Room object that was created when the channel was first subscribed to by the consumer when that
+    # subscriber wants to say something in the room.
+    #
+    # 
     class Base
       include Callbacks
       include PeriodicTimers