Finished class documentation

6 files changed, 43 insertions, 4 deletions

diff --git a/lib/action_cable/remote_connections.rb b/lib/action_cable/remote_connections.rb
index df390073de..ae7145891c 100644
--- a/lib/action_cable/remote_connections.rb
+++ b/lib/action_cable/remote_connections.rb
@@ -42,6 +42,7 @@ module ActionCable
           server.broadcast internal_redis_channel, type: 'disconnect'
         end
 
+        # Returns all the identifiers that were applied to this connection.
         def identifiers
           server.connection_identifiers
         end
diff --git a/lib/action_cable/server/base.rb b/lib/action_cable/server/base.rb
index 3d1d9e71ff..23cd8388bd 100644
--- a/lib/action_cable/server/base.rb
+++ b/lib/action_cable/server/base.rb
@@ -1,5 +1,9 @@
 module ActionCable
   module Server
+    # A singleton ActionCable::Server instance is available via ActionCable.server. It's used by the rack process that starts the cable server, but
+    # also by the user to reach the RemoteConnections instead for finding and disconnecting connections across all servers.
+    #
+    # Also, this is the server instance used for broadcasting. See Broadcasting for details.
     class Base
       include ActionCable::Server::Broadcasting
       include ActionCable::Server::Connections
@@ -12,14 +16,22 @@ module ActionCable
       def initialize
       end
 
+      # Called by rack to setup the server.
       def call(env)
         config.connection_class.new(self, env).process
       end
 
+      # Gateway to RemoteConnections. See that class for details.
+      def remote_connections
+        @remote_connections ||= RemoteConnections.new(self)
+      end
+
+      # The thread worker pool for handling all the connection work on this server. Default size is set by config.worker_pool_size.
       def worker_pool
         @worker_pool ||= ActionCable::Server::Worker.pool(size: config.worker_pool_size)
       end
 
+      # Requires and returns an array of all the channel class constants in this application.
       def channel_classes
         @channel_classes ||= begin
           config.channel_paths.each { |channel_path| require channel_path }
@@ -27,14 +39,12 @@ module ActionCable
         end
       end
 
-      def remote_connections
-        @remote_connections ||= RemoteConnections.new(self)
-      end
-
+      # The redis pubsub adapter used for all streams/broadcasting.
       def pubsub
         @pubsub ||= redis.pubsub
       end
 
+      # The EventMachine Redis instance used by the pubsub adapter.
       def redis
         @redis ||= EM::Hiredis.connect(config.redis[:url]).tap do |redis|
           redis.on(:reconnect_failed) do
@@ -45,6 +55,7 @@ module ActionCable
         end
       end
 
+      # All the identifiers applied to the connection class associated with this server.
       def connection_identifiers
         config.connection_class.identifiers
       end
diff --git a/lib/action_cable/server/broadcasting.rb b/lib/action_cable/server/broadcasting.rb
index 105ccb2b5c..c082e87e56 100644
--- a/lib/action_cable/server/broadcasting.rb
+++ b/lib/action_cable/server/broadcasting.rb
@@ -1,14 +1,35 @@
 module ActionCable
   module Server
+    # Broadcasting is how other parts of your application can send messages to the channel subscribers. As explained in Channel, most of the time, these
+    # broadcastings are streamed directly to the clients subscribed to the named broadcasting. Let's explain with a full-stack example:
+    #
+    #   class WebNotificationsChannel < ApplicationCable::Channel
+    #      def subscribed
+    #        stream_from "web_notifications_#{current_user.id}"
+    #      end
+    #    end
+    #
+    #    # Somewhere in your app this is called, perhaps from a NewCommentJob
+    #    ActionCable.server.broadcast \
+    #      "web_notifications_1", { title: 'New things!', body: 'All shit fit for print' }
+    #
+    #    # Client-side coffescript which assumes you've already requested the right to send web notifications
+    #    BC.cable.createSubscription "WebNotificationsChannel",
+    #      received: (data) ->
+    #       web_notification = new Notification data['title'], body: data['body']
     module Broadcasting
+      # Broadcast a hash directly to a named <tt>broadcasting</tt>. It'll automatically be JSON encoded.
       def broadcast(broadcasting, message)
         broadcaster_for(broadcasting).broadcast(message)
       end
 
+      # Returns a broadcaster for a named <tt>broadcasting</tt> that can be reused. Useful when you have a object that
+      # may need multiple spots to transmit to a specific broadcasting over and over.
       def broadcaster_for(broadcasting)
         Broadcaster.new(self, broadcasting)
       end
 
+      # The redis instance used for broadcasting. Not intended for direct user use.
       def broadcasting_redis
         @broadcasting_redis ||= Redis.new(config.redis)
       end      
diff --git a/lib/action_cable/server/configuration.rb b/lib/action_cable/server/configuration.rb
index c5783f30e0..ac9fa7b085 100644
--- a/lib/action_cable/server/configuration.rb
+++ b/lib/action_cable/server/configuration.rb
@@ -1,5 +1,7 @@
 module ActionCable
   module Server
+    # An instance of this configuration object is available via ActionCable.server.config, which allows you to tweak the configuration points
+    # in a Rails config initializer.
     class Configuration
       attr_accessor :logger, :log_tags
       attr_accessor :connection_class, :worker_pool_size
diff --git a/lib/action_cable/server/connections.rb b/lib/action_cable/server/connections.rb
index 4a3fa3c621..15d7c3c8c7 100644
--- a/lib/action_cable/server/connections.rb
+++ b/lib/action_cable/server/connections.rb
@@ -1,5 +1,8 @@
 module ActionCable
   module Server
+    # Collection class for all the connections that's been established on this specific server. Remember, usually you'll run many cable servers, so
+    # you can't use this collection as an full list of all the connections established against your application. Use RemoteConnections for that.
+    # As such, this is primarily for internal use.
     module Connections
       def connections
         @connections ||= []
diff --git a/lib/action_cable/server/worker.rb b/lib/action_cable/server/worker.rb
index aa807bdf59..01d2c25c8a 100644
--- a/lib/action_cable/server/worker.rb
+++ b/lib/action_cable/server/worker.rb
@@ -1,5 +1,6 @@
 module ActionCable
   module Server
+    # Worker used by Server.send_async to do connection work in threads. Only for internal use.
     class Worker
       include ActiveSupport::Callbacks
       include Celluloid