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

@@ -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.
    */

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.