add comments

services/real-time/app/coffee/ChannelManager.coffee

@@ -17,6 +17,9 @@ module.exports = ChannelManager =
     subscribe: (rclient, baseChannel, id) ->
         clientChannelMap = @getClientMapEntry(rclient)
         channel = "#{baseChannel}:#{id}"
+        # we track pending subscribes because we want to be sure that the
+        # channel is active before letting the client join the doc or project,
+        # so that events are not lost.
         if clientChannelMap.has(channel)
             logger.warn {channel}, "subscribe already actioned"
             # return the existing subscribe promise, so we can wait for it to resolve
@@ -33,6 +36,9 @@ module.exports = ChannelManager =
     unsubscribe: (rclient, baseChannel, id) ->
         clientChannelMap = @getClientMapEntry(rclient)
         channel = "#{baseChannel}:#{id}"
+        # we don't need to track pending unsubscribes, because we there is no
+        # harm if events continue to arrive on the channel while the unsubscribe
+        # command in pending.
         if !clientChannelMap.has(channel)
             logger.error {channel}, "not subscribed - shouldn't happen"
         else

services/real-time/app/coffee/RoomManager.coffee

@@ -2,7 +2,7 @@ logger = require 'logger-sharelatex'
 {EventEmitter} = require 'events'
 
 IdMap = new Map() # keep track of whether ids are from projects or docs
-RoomEvents = new EventEmitter()
+RoomEvents = new EventEmitter() # emits {project,doc}-active and {project,doc}-empty events
 
 # Manage socket.io rooms for individual projects and docs
 #
@@ -49,6 +49,7 @@ module.exports = RoomManager =
         if beforeCount == 0
             logger.log {entity, id}, "room is now active"
             RoomEvents.once "#{entity}-subscribed-#{id}", (err) ->
+                # only allow the client to join when all the relevant channels have subscribed
                 logger.log {client: client.id, entity, id, beforeCount}, "client joined room after subscribing channel"
                 client.join id
                 callback(err)