Bug 1539210 - Document TabSession and Session constructor arguments. r=ato

Depends on D25578

Differential Revision: https://phabricator.services.mozilla.com/D25770

--HG--
extra : moz-landing-system : lando

remote/sessions/Session.jsm

@@ -14,11 +14,27 @@ const {RemoteAgentError} = ChromeUtils.import("chrome://remote/content/Error.jsm
  * A session represents exactly one client WebSocket connection.
  *
  * Every new WebSocket connections is associated with one session that
- * deals with despatching incoming command requests to the right
+ * deals with dispatching incoming command requests to the right
  * target, sending back responses, and propagating events originating
  * from domains.
+ * Then, some subsequent Sessions may be created over a single WebSocket
+ * connection. In this case, the subsequent session will have an `id`
+ * being passed to their constructor and each packet of these sessions
+ * will have a `sessionId` attribute in order to filter the packets
+ * by session both on client and server side.
  */
 class Session {
+  /**
+   * @param Connection connection
+   *        The connection used to communicate with the server.
+   * @param Target target
+   *        The target to which this session communicates with.
+   * @param Number id (optional)
+   *        If this session isn't the default one used for the HTTP endpoint we
+   *        connected to, the session requires an id to distinguish it from the default
+   *        one. This id is used to filter our request, responses and events between
+   *        all active sessions.
+   */
   constructor(connection, target, id) {
     this.connection = connection;
     this.target = target;

remote/sessions/TabSession.jsm

@@ -9,7 +9,25 @@ var EXPORTED_SYMBOLS = ["TabSession"];
 const {Domains} = ChromeUtils.import("chrome://remote/content/domains/Domains.jsm");
 const {Session} = ChromeUtils.import("chrome://remote/content/sessions/Session.jsm");
 
+/**
+ * A session to communicate with a given tab
+ */
 class TabSession extends Session {
+  /**
+   * @param Connection connection
+   *        The connection used to communicate with the server.
+   * @param TabTarget target
+   *        The tab target to which this session communicates with.
+   * @param Number id (optional)
+   *        If this session isn't the default one used for the HTTP endpoint we
+   *        connected to, the session requires an id to distinguish it from the default
+   *        one. This id is used to filter our request, responses and events between
+   *        all active sessions.
+   * @param Session parentSession (optional)
+   *        If this isn't the default session, optional hand over a session to which
+   *        we will forward all request responses and events via
+   *        `Target.receivedMessageFromTarget` events.
+   */
   constructor(connection, target, id, parentSession) {
     super(connection, target, id);
     this.parentSession = parentSession;