Documentation and cleanup

lib/Connectors/IwcConnector.coffee

@@ -25,6 +25,9 @@ createIwcConnector = (callback, options)->
 
   #
   # The Iwc Connector adds support for the Inter-Widget-Communication protocol that is used in the Role-SDK.
+  #
+  # You must not use your own IWC client when using this connector!!
+  #
   # @see http://dbis.rwth-aachen.de/cms/projects/the-xmpp-experience#interwidget-communication
   # @see http://dbis.rwth-aachen.de/cms/projects/ROLE
   #
@@ -34,7 +37,7 @@ createIwcConnector = (callback, options)->
     # @param {Engine} engine The transformation engine
     # @param {HistoryBuffer} HB
     # @param {Array<Function>} execution_listener You must ensure that whenever an operation is executed, every function in this Array is called.
-    # @param {Yatta} yatta The Yatta framework.
+    # @param {YattaFramework} yatta The Yatta framework.
     #
     constructor: (@engine, @HB, @execution_listener, @yatta)->
       @duiClient = duiClient
@@ -75,20 +78,11 @@ createIwcConnector = (callback, options)->
       @iwcHandler["Yatta_get_HB_element"] = [sendHistoryBuffer]
 
     #
-    # This function is called whenever an operation was executed.
-    # @param {Operation} o The operation that was executed.
+    # Set your own IWC handler. It will be called after Yatta consumed the
+    # data from the received intent.
     #
-    send: (o)->
-      if o.uid.creator is @HB.getUserId() and (typeof o.uid.op_number isnt "string")
-        @sendIwcIntent "Yatta_new_operation", o
-
-    #
-    # This function is called whenever an operation was received from another peer.
-    # @param {Operation} o The operation that was received.
-    #
-    receive: (o)->
-      if o.uid.creator isnt @HB.getUserId()
-        @engine.applyOp o
+    setIwcHandler: (f)->
+      userIwcHandler = f
 
     #
     # Helper for sending iwc intents.
@@ -114,8 +108,23 @@ createIwcConnector = (callback, options)->
 
       @duiClient.sendIntent(intent)
 
-    setIwcHandler: (f)->
-      userIwcHandler = f
+    #
+    # @private
+    # This function is called whenever an operation was executed.
+    # @param {Operation} o The operation that was executed.
+    #
+    send: (o)->
+      if o.uid.creator is @HB.getUserId() and (typeof o.uid.op_number isnt "string")
+        @sendIwcIntent "Yatta_new_operation", o
+
+    #
+    # @private
+    # This function is called whenever an operation was received from another peer.
+    # @param {Operation} o The operation that was received.
+    #
+    receive: (o)->
+      if o.uid.creator isnt @HB.getUserId()
+        @engine.applyOp o
 
 
   init = ()->

lib/Connectors/PeerJsConnector.coffee

@@ -19,6 +19,8 @@ createPeerJsConnector = ()->
 
 
   #
+  # PeerJs is a Framework that enables you to connect to other peers. You just need the
+  # user-id of the peer (browser/client). And then you can connect to it.
   # @see http://peerjs.com
   #
   class PeerJsConnector
@@ -38,25 +40,46 @@ createPeerJsConnector = ()->
         @addConnection conn
 
       send_ = (o)=>
-        @send o
+        if o.uid.creator is @HB.getUserId() and (typeof o.uid.op_number isnt "string")
+          for conn_id,conn of @connections
+            conn.send
+              op: o
       @execution_listener.push send_
 
+    #
+    # Connect the Framework to another peer. Therefore you have to receive his
+    # user_id. If the other peer is connected to other peers, the PeerJsConnector
+    # will automatically connect to them too.
+    #
+    # Transmitting the user_id is your job.
+    # See [TextEditing](../../examples/TextEditing/) for a nice example
+    # on how to do that with urls.
+    #
+    # @param id {String} Connection id
+    #
     connectToPeer: (id)->
       if not @connections[id]? and id isnt @yatta.getUserId()
         @addConnection peer.connect id
 
+    #
+    # Receive the id of every connected peer.
+    # @return {Array<String>} A list of Peer-Ids
+    #
     getAllConnectionIds: ()->
       for conn_id of @connections
         conn_id
 
     #
-    # What this method does:
-    # * Send state vector
-    # * Receive HB -> apply them
-    # * Send connections
-    # * Receive Connections -> Connect to unknow connections
+    # Adds an existing connection to this connector.
+    # @param conn {PeerJsConnection}
     #
     addConnection: (conn)->
+      #
+      # What this method does:
+      # * Send state vector
+      # * Receive HB -> apply them
+      # * Send connections
+      # * Receive Connections -> Connect to unknow connections
       @connections[conn.peer] = conn
       initialized_me = false
       initialized_him = false
@@ -91,24 +114,6 @@ createPeerJsConnector = ()->
           setTimeout sendStateVector, 100
       sendStateVector()
 
-    #
-    # This function is called whenever an operation was executed.
-    # @param {Operation} o The operation that was executed.
-    #
-    send: (o)->
-      if o.uid.creator is @HB.getUserId() and (typeof o.uid.op_number isnt "string")
-        for conn_id,conn of @connections
-          conn.send
-            op: o
-
-    #
-    # This function is called whenever an operation was received from another peer.
-    # @param {Operation} o The operation that was received.
-    #
-    receive: (o)->
-      if o.uid.creator isnt @HB.getUserId()
-        @engine.applyOp o
-
   peer.on 'open', (id)->
     callback PeerJsConnector, id
 

lib/Connectors/TestConnector.coffee

@@ -4,6 +4,7 @@ _ = require "underscore"
 module.exports = (user_list)->
 
   #
+  # @nodoc
   # A trivial Connector that simulates network delay.
   #
   class TestConnector