Document the JavaScript classes

4 files changed, 58 insertions, 0 deletions

diff --git a/lib/assets/javascripts/cable/connection.js.coffee b/lib/assets/javascripts/cable/connection.js.coffee
index 87fd038a6f..464f0c1ff7 100644
--- a/lib/assets/javascripts/cable/connection.js.coffee
+++ b/lib/assets/javascripts/cable/connection.js.coffee
@@ -1,3 +1,4 @@
+# Encapsulate the cable connection held by the consumer. This is an internal class not intended for direct user manipulation.
 class Cable.Connection
   constructor: (@consumer) ->
     @open()
diff --git a/lib/assets/javascripts/cable/connection_monitor.js.coffee b/lib/assets/javascripts/cable/connection_monitor.js.coffee
index 1f8ce4eb20..cac65d9043 100644
--- a/lib/assets/javascripts/cable/connection_monitor.js.coffee
+++ b/lib/assets/javascripts/cable/connection_monitor.js.coffee
@@ -1,3 +1,5 @@
+# Responsible for ensuring the cable connection is in good health by validating the heartbeat pings sent from the server, and attempting
+# revival reconnections if things go astray. Internal class, not intended for direct user manipulation.
 class Cable.ConnectionMonitor
   identifier: Cable.PING_IDENTIFIER
 
diff --git a/lib/assets/javascripts/cable/subscription.js.coffee b/lib/assets/javascripts/cable/subscription.js.coffee
index b60033098a..5b024d4e15 100644
--- a/lib/assets/javascripts/cable/subscription.js.coffee
+++ b/lib/assets/javascripts/cable/subscription.js.coffee
@@ -1,3 +1,48 @@
+# A new subscription is created through the Cable.Subscriptions instance available on the consumer. 
+# It provides a number of callbacks and a method for calling remote procedure calls on the corresponding 
+# Channel instance on the server side.
+#
+# An example demonstrates the basic functionality:
+#
+#   App.appearance = App.cable.subscriptions.create "AppearanceChannel",
+#     connected: ->
+#       # Called once the subscription has been successfully completed
+#   
+#     appear: ->
+#       @perform 'appear', appearing_on: @appearingOn()
+#   
+#     away: ->
+#       @perform 'away'
+#   
+#     appearingOn: ->
+#       $('main').data 'appearing-on'
+#
+# The methods #appear and #away forward their intent to the remote AppearanceChannel instance on the server
+# by calling the `@perform` method with the first parameter being the action (which maps to AppearanceChannel#appear/away).
+# The second parameter is a hash that'll get JSON encoded and made available on the server in the data parameter.
+#
+# This is how the server component would look:
+#
+#   class AppearanceChannel < ApplicationCable::Channel
+#     def subscribed
+#       current_user.appear
+#     end
+#   
+#     def unsubscribed
+#       current_user.disappear
+#     end
+#   
+#     def appear(data)
+#       current_user.appear on: data['appearing_on']
+#     end
+#   
+#     def away
+#       current_user.away
+#     end
+#   end
+#
+# The "AppearanceChannel" name is automatically mapped between the client-side subscription creation and the server-side Ruby class name.
+# The AppearanceChannel#appear/away public methods are exposed automatically to client-side invocation through the @perform method.
 class Cable.Subscription
   constructor: (@subscriptions, params = {}, mixin) ->
     @identifier = JSON.stringify(params)
diff --git a/lib/assets/javascripts/cable/subscriptions.js.coffee b/lib/assets/javascripts/cable/subscriptions.js.coffee
index 884257a12d..e1dfff7511 100644
--- a/lib/assets/javascripts/cable/subscriptions.js.coffee
+++ b/lib/assets/javascripts/cable/subscriptions.js.coffee
@@ -1,3 +1,11 @@
+# Collection class for creating (and internally managing) channel subscriptions. The only method intended to be triggered by the user
+# us Cable.Subscriptions#create, and it should be called through the consumer like so:
+#
+#   @App = {}
+#   App.cable = Cable.createConsumer "http://example.com/accounts/1"
+#   App.appearance = App.cable.subscriptions.create "AppearanceChannel"
+#
+# For more details on how you'd configure an actual channel subscription, see Cable.Subscription.
 class Cable.Subscriptions
   constructor: (@consumer) ->
     @subscriptions = []
@@ -7,6 +15,8 @@ class Cable.Subscriptions
     params = if typeof channel is "object" then channel else {channel}
     new Cable.Subscription this, params, mixin
 
+  # Private
+
   add: (subscription) ->
     @subscriptions.push(subscription)
     @notify(subscription, "initialized")