From e490a53de2c8cc83bb1b472cf118f31df1f79e64 Mon Sep 17 00:00:00 2001
From: Alexandre Poirot <poirot.alex@gmail.com>
Date: Mon, 24 Sep 2018 16:24:07 +0000
Subject: [PATCH] Bug 1492826 - Better document TabTarget.attach as well as
 DebuggerClient.attachTarget and attachConsole. r=jdescottes

Depends On D6162

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

--HG--
extra : moz-landing-system : lando
---
 devtools/client/framework/target.js       |  4 ++++
 devtools/shared/client/debugger-client.js | 27 +++++++++++++++++++++--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/devtools/client/framework/target.js b/devtools/client/framework/target.js
index 64877ad28437..46442a8fd5bf 100644
--- a/devtools/client/framework/target.js
+++ b/devtools/client/framework/target.js
@@ -466,6 +466,10 @@ TabTarget.prototype = {
    *
    * This method will mainly call `attach` request on the target actor as well
    * as the console actor.
+   * See DebuggerClient.attachTarget and DebuggerClient.attachConsole for more info.
+   * It also starts listenings to events the target actor will start emitting
+   * after being attached, like `tabDetached` and `frameUpdate`
+   *
    * For webextension, it also preliminary converts addonTargetActor to a
    * WebExtensionTargetActor.
    */
diff --git a/devtools/shared/client/debugger-client.js b/devtools/shared/client/debugger-client.js
index d0a39e0c74e6..d6eb6685b47b 100644
--- a/devtools/shared/client/debugger-client.js
+++ b/devtools/shared/client/debugger-client.js
@@ -327,7 +327,13 @@ DebuggerClient.prototype = {
   },
 
   /**
-   * Attach to a target actor.
+   * Attach to a target actor:
+   *
+   *  - start watching for new documents (emits `tabNativated` messages)
+   *  - start watching for inner iframe updates (emits `frameUpdate` messages)
+   *  - retrieve the thread actor:
+   *    Instantiates a new ThreadActor that can be later attached to in order to
+   *    debug JS sources in the document.
    *
    * @param string targetActor
    *        The target actor ID for the tab to attach.
@@ -395,7 +401,24 @@ DebuggerClient.prototype = {
   },
 
   /**
-   * Attach to a Web Console actor.
+   * Attach to a Web Console actor. Depending on the listeners being passed as second
+   * arguments, starts listening for:
+   * - PageError:
+   *   Javascript error happening in the debugged context
+   * - ConsoleAPI:
+   *   Calls made to console.* API
+   * - NetworkActivity:
+   *   Http requests made in the debugged context
+   * - FileActivity:
+   *   Any requests made for a file:// or ftp:// URL. It can be the document or any of
+   *   its resources, like images.
+   * - ReflowActivity:
+   *   Any reflow made by the document being debugged.
+   * - ContentProcessMessages:
+   *   When the console actor runs in the parent process, also fetch calls made to
+   *   console.* API in all the content processes.
+   * - DocumentEvents:
+   *   Listen for DOMContentLoaded and load events.
    *
    * @param string consoleActor
    *        The ID for the console actor to attach to.