Bug 1622836 - Added documentation for nsIPromptService. r=johannh DONTBUILD

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

docs/conf.py

@@ -56,6 +56,7 @@ js_source_path = [
     'toolkit/components/extensions/parent',
     'toolkit/components/featuregates',
     'toolkit/mozapps/extensions',
+    'toolkit/components/prompts/src',
 ]
 root_for_relative_js_paths = '.'
 jsdoc_config_path = 'jsdoc.json'

toolkit/components/prompts/docs/index.rst

@@ -0,0 +1,10 @@
+=======
+Prompts
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   nsIPromptService
+   nsIPromptService-reference
+   modalTypes

toolkit/components/prompts/docs/modalTypes.rst

@@ -0,0 +1,95 @@
+==================
+Prompt Modal Types
+==================
+
+Window Prompts
+--------------
+
+Window prompts are system prompts. They are clearly distinguishable from website
+content and can be opened with or without a parent window.
+While a window prompt is open, the parent window cannot be interacted with.
+That means the user can not close the window or switch tabs.
+Providing a parent window is optional, but highly encouraged. If you do not
+pass a parent the implementation will try to find one or fallback to aborted
+standalone window.
+
+**When to use**: This should be reserved for important browser-wide messages
+with the intent to block any further user interaction until the message has been
+read.
+
+**Flag**: `MODAL_TYPE_WINDOW`
+
+.. caution::
+
+  When using window prompts, make sure they can not be spawned by web content.
+  We've seen `cases <https://bugzilla.mozilla.org/show_bug.cgi?id=1571003>`_
+  of DoS attacks in the wild where websites spammed window prompts to lock up
+  the browser.
+  This prompt type should only be used when necessary and with proper rate
+  limiting. Most of the time, a tab prompt can be be used.
+
+.. figure:: modal-type-window.png
+   :width: 425px
+   :height: 230px
+   :alt: Screenshot of a window prompt.
+
+   Window alert prompt
+
+Tab Prompts
+-----------
+
+Tab prompts are system prompts like window prompts. As opposed to window
+prompts, they are tab modal and don't steal focus from the parent window.
+Multiple tab prompts cannot be shown at the same time. When opening additional
+prompts, they are FIFO queued.
+
+When the user closes the tab or navigates to a different URI, prompts associated
+with the given tab are closed.
+In this case an exception will be thrown:
+
+.. code-block::
+
+    /*
+    Exception: prompt aborted by user
+    undefined:425
+    */
+
+**When to use**: This prompt should be used for dialogs that were caused by web
+content and thus should be bound to the scope and lifetime of a specific tab,
+but should still look like secure browser UI. Examples are HTTP Auth prompt or
+the dialog to add a new search provider for the current website.
+
+**Flag**: `MODAL_TYPE_TAB`
+
+
+.. figure:: modal-type-tab.png
+   :width: 425px
+   :height: 230px
+   :alt: Screenshot of a tab prompt.
+
+   Tab alert prompt
+
+Content Prompts
+---------------
+
+Content prompts are like tab prompts, but they belong to the web content. Thus,
+they are positioned in the center of the selected browser.
+
+**When to use**: The prompt is triggered by or as a result of an action of web
+content and is **not** intended to look like secure browser UI.
+
+**Flag**: `MODAL_TYPE_CONTENT`
+
+.. figure:: modal-type-content.png
+   :width: 425px
+   :height: 230px
+   :alt: Screenshot of a content prompt.
+
+   Content alert prompt
+
+
+Disabling tab/content modal prompts
+-----------------------------------
+You can disable tab and content modal prompts and get back window-modal prompts
+by setting the `prompts.tab_modal.enabled` preference to `false`.
+This pref might be removed in the future.

toolkit/components/prompts/docs/nsIPromptService-reference.rst

@@ -0,0 +1,10 @@
+========================
+Prompt Service Reference
+========================
+
+This is the JSDoc from the Prompter.jsm implementation. You can find the full
+interface definition in
+`nsIPromptService.idl <https://searchfox.org/mozilla-central/source/toolkit/components/windowwatcher/nsIPromptService.idl>`_.
+
+.. js:autoclass:: Prompter
+  :members:

toolkit/components/prompts/docs/nsIPromptService.rst

@@ -0,0 +1,195 @@
+==============
+Prompt Service
+==============
+
+The `nsIPromptService` provides methods for opening various types of prompts.
+See the `interface documentation <nsIPromptService-reference.html>`_ for a list
+of prompt types.
+Every prompt method has 3 different versions:
+
+- **Prompt by window**:
+  This is considered the legacy way of prompting and only works if the window
+  you want to prompt for is in the same process.
+  Only supports window prompts.
+
+- **Prompt by browsing context (synchronous)**:
+  Use a browsing context as parent for the prompt. Works cross process from
+  parent and content process.
+
+- **Prompt by browsing context (asynchronous)**:
+  Returns a promise which resolves once the prompt closes.
+
+
+The synchronous prompt methods use call by reference (XPCOM `inout` or `out`) to
+return the updated prompt arguments to the caller.
+When prompting async the arguments are passed in by value. Prompt results are
+returned in an `nsIPropertyBag` when the Promise resolves.
+
+
+.. note::
+    If you don't provide a parent window or browsing context the prompt service
+    will fallback to a window prompt.
+    The same goes for browsing contexts of chrome windows, because there is no
+    clear association to a browser / tab.
+
+
+Examples
+--------
+
+JavaScript Sync
+~~~~~~~~~~~~~~~
+
+Here is an example of opening a confirm prompt from JavaScript. We are in the
+parent process and we want to show a tab prompt:
+
+.. code-block:: javascript
+
+    // Get the browsing context for the currently selected tab
+    let browsingContext = gBrowser.selectedBrowser.browsingContext;
+
+    // Specify prompt type, can be MODAL_TYPE_TAB, MODAL_TYPE_CONTENT,
+    // MODAL_TYPE_WINDOW
+    let modalType = Services.prompt.MODAL_TYPE_TAB;
+
+    // Object for checkbox state to pass by reference.
+    let check = { value: false };
+
+    // Prompt synchronously and store result
+    let confirmed = Services.prompt.confirmCheckBC(browsingContext, modalType,
+    "My Title", "Hello, World!", "Check this box if you agree", check);
+
+    // check.value now contains final checkbox state
+    // confirmed is a boolean which indicates whether the user pressed ok (true)
+    // or cancel (false)
+    console.debug("User checked checkbox?", check.value);
+    console.debug("User confirmed prompt?", confirmed);
+
+
+JavaScript Async
+~~~~~~~~~~~~~~~~
+
+The same prompt as above, but called async:
+
+.. code-block:: javascript
+
+    // Get the browsing context for the currently selected tab
+    let browsingContext = gBrowser.selectedBrowser.browsingContext;
+
+    // Specify prompt type, can be MODAL_TYPE_TAB, MODAL_TYPE_CONTENT,
+    // MODAL_TYPE_WINDOW
+    let modalType = Services.prompt.MODAL_TYPE_TAB;
+
+    // Note that the checkbox state variable is not an object in this case,
+    because we get the checkbox result via the result object.
+    let check = false;
+
+    // Prompt asynchronously and await result
+    let propBag = await Services.prompt.asyncConfirmCheck(browsingContext,
+                                                          modalType,
+                                                          "My Title",
+                                                          "Hello, World!",
+                                                          "Check this box if you agree",
+                                                          check);
+
+    let ok = propBag.getProperty("ok");
+    let checked = propBag.getProperty("checked");
+
+    // ok is the boolean indicating if the user clicked "ok" (true) or
+    // "cancel" (false).
+    // checked is a boolean indicating the final checkbox state
+    console.debug("User checked checkbox?", checked);
+    console.debug("User confirmed prompt?", ok);
+
+
+C++ Sync
+~~~~~~~~
+
+.. code-block:: c++
+
+      nsCOMPtr<nsIPromptService> promptSvc =
+        do_GetService("@mozilla.org/embedcomp/prompt-service;1");
+
+      if(!promptSvc) {
+        // Error handling
+        return;
+      }
+
+      // Assuming you have the browsing context as a member.
+      // You might need to get the browsing context from somewhere else.
+      BrowsingContext* bc = mBrowsingContext;
+
+      bool ok;
+      bool checked = false;
+
+      nsresult rv = promptSvc->confirmCheck(mBrowsingContext,
+                                            nsIPromptService::MODAL_TYPE_TAB,
+                                            NS_LITERAL_CSTRING("My Title")
+                                            NS_LITERAL_CSTRING("Hello, World!"),
+                                            NS_LITERAL_CSTRING("Check this box if you agree"),
+                                            &checked, &ok);
+
+      // ok is the boolean indicating if the user clicked "ok" (true) or
+      // "cancel" (false).
+      // checked is a boolean indicating the final checkbox state
+
+C++ Async
+~~~~~~~~~
+
+.. code-block:: c++
+
+      nsCOMPtr<nsIPromptService> promptSvc =
+        do_GetService("@mozilla.org/embedcomp/prompt-service;1");
+
+      if(!promptSvc) {
+        // Error handling
+        return;
+      }
+
+      bool checked = false;
+      Promise* promise;
+
+      // Assuming you have the browsing context as a member.
+      // You might need to get the browsing context from somewhere else.
+      BrowsingContext* bc = mBrowsingContext;
+
+      // As opposed to the sync case, here we pass the checked flag by value
+      nsresult rv = promptSvc->confirmCheckAsync(mBrowsingContext,
+                                                 nsIPromptService::MODAL_TYPE_TAB, NS_LITERAL_CSTRING("My Title"),
+                                                 NS_LITERAL_CSTRING("Hello, World!"),
+                                                 NS_LITERAL_CSTRING("Check this box if you agree"),
+                                                 checked, promise);
+
+      // Attach a promise handler
+      RefPtr<PromptHandler> handler = new PromptHandler(promise);
+      promise->AppendNativeHandler(handler);
+
+Then, in your promise handler callback function:
+
+.. code-block:: c++
+
+      void PromptHandler::ResolvedCallback(JSContext* aCx,
+                                       JS::Handle<JS::Value> aValue) {
+        JS::Rooted<JSObject*> detailObj(aCx, &aValue.toObject());
+
+        // Convert the JSObject back to a property bag
+        nsresult rv;
+        nsCOMPtr<nsIPropertyBag2> propBag;
+        rv = UnwrapArg<nsIPropertyBag2>(aCx, detailObj, getter_AddRefs(propBag));
+        if (NS_FAILED(rv)) return;
+
+        bool ok;
+        bool checked;
+        propBag->GetPropertyAsBool(NS_LITERAL_STRING("ok"), &ok);
+        propBag->GetPropertyAsBool(NS_LITERAL_STRING("checked"), &checked);
+
+        // ok is the boolean indicating if the user clicked "ok" (true) or
+        // "cancel" (false).
+        // checked is a boolean indicating the final checkbox state.
+      }
+
+
+
+
+
+For a full list of prompt methods check
+`nsIPromptService reference <nsIPromptService-reference.html>`_.

toolkit/components/prompts/moz.build

@@ -10,6 +10,11 @@ with Files('**'):
 
 DIRS += ['src']
 
+SPHINX_TREES['prompts'] = 'docs'
+
+with Files('docs/**'):
+    SCHEDULES.exclusive = ['docs']
+
 MOCHITEST_MANIFESTS += ['test/mochitest.ini']
 MOCHITEST_CHROME_MANIFESTS += ['test/chrome.ini']
 

toolkit/components/prompts/src/Prompter.jsm

@@ -20,6 +20,10 @@ function Prompter() {
   // Note that EmbedPrompter clones this implementation.
 }
 
+/**
+ * Implements nsIPromptService and nsIPromptFactory
+ * @class Prompter
+ */
 Prompter.prototype = {
   classID: Components.ID("{1c978d25-b37f-43a8-a2d6-0c7a239ead87}"),
   QueryInterface: ChromeUtils.generateQI([
@@ -58,66 +62,227 @@ Prompter.prototype = {
 
   /* ----------  nsIPromptService  ---------- */
 
+  /**
+   * Puts up an alert dialog with an OK button.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   */
   alert(domWin, title, text) {
     let p = this.pickPrompter({ domWin });
     p.alert(title, text);
   },
 
+  /**
+   * Puts up an alert dialog with an OK button.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   */
   alertBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     p.alert(...promptArgs);
   },
 
+  /**
+   * Puts up an alert dialog with an OK button.
+   *
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @returns {Promise} A promise which resolves when the prompt is dismissed.
+   */
   asyncAlert(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.alert(...promptArgs);
   },
 
+  /**
+   * Puts up an alert dialog with an OK button and a labeled checkbox.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   */
   alertCheck(domWin, title, text, checkLabel, checkValue) {
     let p = this.pickPrompter({ domWin });
     p.alertCheck(title, text, checkLabel, checkValue);
   },
 
+  /**
+   * Puts up an alert dialog with an OK button and a labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   */
   alertCheckBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     p.alertCheck(...promptArgs);
   },
 
+  /**
+   * Puts up an alert dialog with an OK button and a labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   * @param {Boolean} checkValue - The initial checked state of the checkbox.
+   * @returns {Promise<nsIPropertyBag<{ checked: Boolean }>>}
+   *          A promise which resolves when the prompt is dismissed.
+   */
   asyncAlertCheck(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.alertCheck(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with OK and Cancel buttons.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   confirm(domWin, title, text) {
     let p = this.pickPrompter({ domWin });
     return p.confirm(title, text);
   },
 
+  /**
+   * Puts up a dialog with OK and Cancel buttons.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   confirmBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.confirm(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with OK and Cancel buttons.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @returns {Promise<nsIPropertyBag<{ ok: Boolean }>>}
+   *          A promise which resolves when the prompt is dismissed.
+   */
   asyncConfirm(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.confirm(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with OK and Cancel buttons and a labeled checkbox.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   */
   confirmCheck(domWin, title, text, checkLabel, checkValue) {
     let p = this.pickPrompter({ domWin });
     return p.confirmCheck(title, text, checkLabel, checkValue);
   },
 
+  /**
+   * Puts up a dialog with OK and Cancel buttons and a labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean} true for OK, false for Cancel
+   */
   confirmCheckBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.confirmCheck(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with OK and Cancel buttons and a labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   * @param {Boolean} checkValue - The initial checked state of the checkbox.
+   * @returns {Promise<nsIPropertyBag<{ ok: Boolean, checked: Boolean }>>}
+   *          A promise which resolves when the prompt is dismissed.
+   */
   asyncConfirmCheck(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.confirmCheck(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox.
+   *
+   * Buttons are numbered 0 - 2. Button 0 is the default button unless one of
+   * the Button Default Flags is specified.
+   *
+   * A button may use a predefined title, specified by one of the Button Title
+   * Flags values.  Each title value can be multiplied by a position value to
+   * assign the title to a particular button.  If BUTTON_TITLE_IS_STRING is
+   * used for a button, the string parameter for that button will be used.  If
+   * the value for a button position is zero, the button will not be shown.
+   *
+   * In general, flags is constructed per the following example:
+   *
+   * flags = (BUTTON_POS_0) * (BUTTON_TITLE_AAA) +
+   *         (BUTTON_POS_1) * (BUTTON_TITLE_BBB) +
+   *         BUTTON_POS_1_DEFAULT;
+   *
+   * where "AAA" and "BBB" correspond to one of the button titles.
+   *
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Number} flags - A combination of Button Flags.
+   * @param {String} button0 - Used when button 0 uses TITLE_IS_STRING.
+   * @param {String} button1 - Used when button 1 uses TITLE_IS_STRING.
+   * @param {String} button2 - Used when button 2 uses TITLE_IS_STRING.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        Null if no checkbox.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method
+   *        is called and the final checked state after this method returns.
+   * @returns {Number} The index of the button pressed.
+   */
   confirmEx(
     domWin,
     title,
@@ -142,31 +307,141 @@ Prompter.prototype = {
     );
   },
 
+  /**
+   * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Number} flags - A combination of Button Flags.
+   * @param {String} button0 - Used when button 0 uses TITLE_IS_STRING.
+   * @param {String} button1 - Used when button 1 uses TITLE_IS_STRING.
+   * @param {String} button2 - Used when button 2 uses TITLE_IS_STRING.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        Null if no checkbox.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Number} The index of the button pressed.
+   */
   confirmExBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.confirmEx(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with up to 3 buttons and an optional, labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Number} flags - A combination of Button Flags.
+   * @param {String} button0 - Used when button 0 uses TITLE_IS_STRING.
+   * @param {String} button1 - Used when button 1 uses TITLE_IS_STRING.
+   * @param {String} button2 - Used when button 2 uses TITLE_IS_STRING.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        Null if no checkbox.
+   * @param {Boolean} checkValue - The initial checked state of the checkbox.
+   * @returns {Promise<nsIPropertyBag<{ buttonNumClicked: Number, checked: Boolean }>>}
+   */
   asyncConfirmEx(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.confirmEx(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with an edit field and an optional, labeled checkbox.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Object} value - Contains the default value for the dialog field
+   *        when this method is called (null value is ok).  Upon return, if
+   *        the user pressed OK, then this parameter contains a newly
+   *        allocated string value.
+   *        Otherwise, the parameter's value is unmodified.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   prompt(domWin, title, text, value, checkLabel, checkValue) {
     let p = this.pickPrompter({ domWin });
     return p.nsIPrompt_prompt(title, text, value, checkLabel, checkValue);
   },
 
+  /**
+   * Puts up a dialog with an edit field and an optional, labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Object} value - Contains the default value for the dialog field
+   *        when this method is called (null value is ok).  Upon return, if
+   *        the user pressed OK, then this parameter contains a newly
+   *        allocated string value.
+   *        Otherwise, the parameter's value is unmodified.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   promptBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.nsIPrompt_prompt(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with an edit field and an optional, labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} value - The default value for the dialog text field.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Boolean} checkValue - The initial checked state of the checkbox.
+   * @returns {Promise<nsIPropertyBag<{ ok: Boolean, checked: Boolean, value: String }>>}
+   *          A promise which resolves when the prompt is dismissed.
+   */
   asyncPrompt(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.nsIPrompt_prompt(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with an edit field, a password field, and an optional,
+   * labeled checkbox.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Object} user - Contains the default value for the username
+   *        field when this method is called (null value is ok).
+   *        Upon return, if the user pressed OK, then this parameter contains
+   *        a newly allocated string value. Otherwise, the parameter's value
+   *        is unmodified.
+   * @param {Object} pass - Contains the default value for the password field
+   *        when this method is called (null value is ok). Upon return, if the
+   *        user pressed OK, this parameter contains a newly allocated string
+   *        value. Otherwise, the parameter's value is unmodified.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   promptUsernameAndPassword(
     domWin,
     title,
@@ -187,16 +462,74 @@ Prompter.prototype = {
     );
   },
 
+  /**
+   * Puts up a dialog with an edit field, a password field, and an optional,
+   * labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Object} user - Contains the default value for the username
+   *        field when this method is called (null value is ok).
+   *        Upon return, if the user pressed OK, then this parameter contains
+   *        a newly allocated string value. Otherwise, the parameter's value
+   *        is unmodified.
+   * @param {Object} pass - Contains the default value for the password field
+   *        when this method is called (null value is ok). Upon return, if the
+   *        user pressed OK, this parameter contains a newly allocated string
+   *        value. Otherwise, the parameter's value is unmodified.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   promptUsernameAndPasswordBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.nsIPrompt_promptUsernameAndPassword(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with an edit field, a password field, and an optional,
+   * labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} user - Default value for the username field.
+   * @param {String} pass - Contains the default value for the password field.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Boolean} checkValue - The initial checked state of the checkbox.
+   * @returns {Promise<nsIPropertyBag<{ ok: Boolean, checked: Boolean, user: String, pass: String }>>}
+   *          A promise which resolves when the prompt is dismissed.
+   */
   asyncPromptUsernameAndPassword(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.nsIPrompt_promptUsernameAndPassword(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with a password field and an optional, labeled checkbox.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Object} pass - Contains the default value for the password field
+   *        when this method is called (null value is ok). Upon return, if the
+   *        user pressed OK, this parameter contains a newly allocated string
+   *        value. Otherwise, the parameter's value is unmodified.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   promptPassword(domWin, title, text, pass, checkLabel, checkValue) {
     let p = this.pickPrompter({ domWin });
     return p.nsIPrompt_promptPassword(
@@ -208,41 +541,175 @@ Prompter.prototype = {
     );
   },
 
+  /**
+   * Puts up a dialog with a password field and an optional, labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {Object} pass - Contains the default value for the password field
+   *        when this method is called (null value is ok). Upon return, if the
+   *        user pressed OK, this parameter contains a newly allocated string
+   *        value. Otherwise, the parameter's value is unmodified.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   promptPasswordBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.nsIPrompt_promptPassword(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog with a password field and an optional, labeled checkbox.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String} pass - Contains the default value for the password field.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Boolean} checkValue - The initial checked state of the checkbox.
+   * @returns {Promise<nsIPropertyBag<{ ok: Boolean, checked: Boolean, pass: String }>>}
+   *          A promise which resolves when the prompt is dismissed.
+   */
   asyncPromptPassword(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.nsIPrompt_promptPassword(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog box which has a list box of strings from which the user
+   * may make a single selection.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String[]} list - The list of strings to display.
+   * @param {Object} selected - Contains the index of the selected item in the
+   *        list when this method returns true.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   select(domWin, title, text, list, selected) {
     let p = this.pickPrompter({ domWin });
     return p.select(title, text, list, selected);
   },
 
+  /**
+   * Puts up a dialog box which has a list box of strings from which the user
+   * may make a single selection.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String[]} list - The list of strings to display.
+   * @param {Object} selected - Contains the index of the selected item in the
+   *        list when this method returns true.
+   * @returns {Boolean} true for OK, false for Cancel.
+   */
   selectBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.select(...promptArgs);
   },
 
+  /**
+   * Puts up a dialog box which has a list box of strings from which the user
+   * may make a single selection.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {String} title - Text to appear in the title of the dialog.
+   * @param {String} text - Text to appear in the body of the dialog.
+   * @param {String[]} list - The list of strings to display.
+   * @returns {Promise<nsIPropertyBag<{ selected: Number, ok: Boolean  }>>}
+   *          A promise which resolves when the prompt is dismissed.
+   */
   asyncSelect(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType, async: true });
     return p.select(...promptArgs);
   },
 
+  /**
+   * Requests a username and a password. Shows a dialog with username and
+   * password field, depending on flags also a domain field.
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {nsIChannel} channel - The channel that requires authentication.
+   * @param {Number} level - Security level of the credential transmission.
+   *        Any of nsIAuthPrompt2.<LEVEL_NONE|LEVEL_PW_ENCRYPTED|LEVEL_SECURE>
+   * @param {nsIAuthInformation} authInfo - Authentication information object.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean}
+   *          true: Authentication can proceed using the values
+   *          in the authInfo object.
+   *          false: Authentication should be cancelled, usually because the
+   *          user did not provide username/password.
+   */
   promptAuth(domWin, channel, level, authInfo, checkLabel, checkValue) {
     let p = this.pickPrompter({ domWin });
     return p.promptAuth(channel, level, authInfo, checkLabel, checkValue);
   },
 
+  /**
+   * Requests a username and a password. Shows a dialog with username and
+   * password field, depending on flags also a domain field.
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {nsIChannel} channel - The channel that requires authentication.
+   * @param {Number} level - Security level of the credential transmission.
+   *        Any of nsIAuthPrompt2.<LEVEL_NONE|LEVEL_PW_ENCRYPTED|LEVEL_SECURE>
+   * @param {nsIAuthInformation} authInfo - Authentication information object.
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after this method returns.
+   * @returns {Boolean}
+   *          true: Authentication can proceed using the values
+   *          in the authInfo object.
+   *          false: Authentication should be cancelled, usually because the
+   *          user did not provide username/password.
+   */
   promptAuthBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.promptAuth(...promptArgs);
   },
 
+  /**
+   * Asynchronously prompt the user for a username and password.
+   * This has largely the same semantics as promptUsernameAndPassword(),
+   * but returns immediately after calling and returns the entered
+   * data in a callback.
+   *
+   * @param {mozIDOMWindowProxy} domWin - The parent window or null.
+   * @param {nsIChannel} channel - The channel that requires authentication.
+   * @param {nsIAuthPromptCallback} callback - Called once the prompt has been
+   *        closed.
+   * @param {nsISupports} context
+   * @param {Number} level - Security level of the credential transmission.
+   *        Any of nsIAuthPrompt2.<LEVEL_NONE|LEVEL_PW_ENCRYPTED|LEVEL_SECURE>
+   * @param {nsIAuthInformation} authInfo
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after the callback.
+   * @returns {nsICancelable} Interface to cancel prompt.
+   */
   asyncPromptAuth(
     domWin,
     channel,
@@ -265,6 +732,30 @@ Prompter.prototype = {
     );
   },
 
+  /**
+   * Asynchronously prompt the user for a username and password.
+   * This has largely the same semantics as promptUsernameAndPassword(),
+   * but returns immediately after calling and returns the entered
+   * data in a callback.
+   *
+   * @param {BrowsingContext} browsingContext - The browsing context the
+   *        prompt should be opened for.
+   * @param {Number} modalType - The modal type of the prompt.
+   *        nsIPromptService.<MODAL_TYPE_WINDOW|MODAL_TYPE_TAB|MODAL_TYPE_CONTENT>
+   * @param {nsIChannel} channel - The channel that requires authentication.
+   * @param {nsIAuthPromptCallback} callback - Called once the prompt has been
+   *        closed.
+   * @param {nsISupports} context
+   * @param {Number} level - Security level of the credential transmission.
+   *        Any of nsIAuthPrompt2.<LEVEL_NONE|LEVEL_PW_ENCRYPTED|LEVEL_SECURE>
+   * @param {nsIAuthInformation} authInfo
+   * @param {String} checkLabel - Text to appear with the checkbox.
+   *        If null, check box will not be shown.
+   * @param {Object} checkValue - Contains the initial checked state of the
+   *        checkbox when this method is called and the final checked state
+   *        after the callback.
+   * @returns {nsICancelable} Interface to cancel prompt.
+   */
   asyncPromptAuthBC(browsingContext, modalType, ...promptArgs) {
     let p = this.pickPrompter({ browsingContext, modalType });
     return p.asyncPromptAuth(...promptArgs);

toolkit/components/windowwatcher/nsIPromptService.idl

@@ -59,10 +59,23 @@ interface nsIPromptService : nsISupports
   void alert(in mozIDOMWindowProxy aParent,
              in wstring aDialogTitle,
              in wstring aText);
+  /**
+   * Like alert, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   void alertBC(in BrowsingContext aBrowsingContext,
                in unsigned long modalType,
                in wstring aDialogTitle,
                in wstring aText);
+  /**
+   * Async version of alertBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   */
   Promise asyncAlert(in BrowsingContext aBrowsingContext,
               in unsigned long modalType,
               in wstring aDialogTitle,
@@ -88,12 +101,27 @@ interface nsIPromptService : nsISupports
                   in wstring aText,
                   in wstring aCheckMsg,
                   inout boolean aCheckState);
+  /**
+   * Like alertCheck, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   void alertCheckBC(in BrowsingContext aBrowsingContext,
                     in unsigned long modalType,
                     in wstring aDialogTitle,
                     in wstring aText,
                     in wstring aCheckMsg,
                     inout boolean aCheckState);
+  /**
+   * Async version of alertCheckBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   *
+   * @resolves nsIPropertyBag { checked: boolean }
+   */
   Promise asyncAlertCheck(in BrowsingContext aBrowsingContext,
                           in unsigned long modalType,
                           in wstring aDialogTitle,
@@ -116,10 +144,25 @@ interface nsIPromptService : nsISupports
   boolean confirm(in mozIDOMWindowProxy aParent,
                   in wstring aDialogTitle,
                   in wstring aText);
+  /**
+   * Like confirm, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   boolean confirmBC(in BrowsingContext aBrowsingContext,
                     in unsigned long modalType,
                     in wstring aDialogTitle,
                     in wstring aText);
+  /**
+   * Async version of confirmBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   *
+   * @resolves nsIPropertyBag { ok: boolean }
+   */
   Promise asyncConfirm(in BrowsingContext aBrowsingContext,
                        in unsigned long modalType,
                        in wstring aDialogTitle,
@@ -147,12 +190,27 @@ interface nsIPromptService : nsISupports
                        in wstring aText,
                        in wstring aCheckMsg,
                        inout boolean aCheckState);
+  /**
+   * Like confirmCheck, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   boolean confirmCheckBC(in BrowsingContext aBrowsingContext,
                          in unsigned long modalType,
                          in wstring aDialogTitle,
                          in wstring aText,
                          in wstring aCheckMsg,
                          inout boolean aCheckState);
+  /**
+   * Async version of confirmCheckBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   *
+   * @resolves nsIPropertyBag { ok: boolean, checked: boolean }
+   */
   Promise asyncConfirmCheck(in BrowsingContext aBrowsingContext,
                             in unsigned long modalType,
                             in wstring aDialogTitle,
@@ -272,6 +330,14 @@ interface nsIPromptService : nsISupports
                     in wstring aButton2Title,
                     in wstring aCheckMsg,
                     inout boolean aCheckState);
+  /**
+   * Like confirmEx, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   int32_t confirmExBC(in BrowsingContext aBrowsingContext,
                       in unsigned long modalType,
                       in wstring aDialogTitle,
@@ -282,6 +348,13 @@ interface nsIPromptService : nsISupports
                       in wstring aButton2Title,
                       in wstring aCheckMsg,
                       inout boolean aCheckState);
+  /**
+   * Async version of confirmExBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   *
+   * @resolves nsIPropertyBag { checked: boolean, buttonNumClicked: int }
+   */
   Promise asyncConfirmEx(in BrowsingContext aBrowsingContext,
                       in unsigned long modalType,
                       in wstring aDialogTitle,
@@ -320,6 +393,14 @@ interface nsIPromptService : nsISupports
                  inout wstring aValue,
                  in wstring aCheckMsg,
                  inout boolean aCheckState);
+  /**
+   * Like prompt, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   boolean promptBC(in BrowsingContext aBrowsingContext,
                    in unsigned long modalType,
                    in wstring aDialogTitle,
@@ -327,6 +408,13 @@ interface nsIPromptService : nsISupports
                    inout wstring aValue,
                    in wstring aCheckMsg,
                    inout boolean aCheckState);
+  /**
+   * Async version of promptBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   *
+   * @resolves nsIPropertyBag { checked: boolean, value: string, ok: boolean }
+   */
   Promise asyncPrompt(in BrowsingContext aBrowsingContext,
                    in unsigned long modalType,
                    in wstring aDialogTitle,
@@ -370,6 +458,14 @@ interface nsIPromptService : nsISupports
                                     inout wstring aPassword,
                                     in wstring aCheckMsg,
                                     inout boolean aCheckState);
+  /**
+   * Like promptUsernameAndPassword, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   boolean promptUsernameAndPasswordBC(in BrowsingContext aBrowsingContext,
                                       in unsigned long modalType,
                                       in wstring aDialogTitle,
@@ -378,6 +474,13 @@ interface nsIPromptService : nsISupports
                                       inout wstring aPassword,
                                       in wstring aCheckMsg,
                                       inout boolean aCheckState);
+  /**
+   * Async version of promptUsernameAndPasswordBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   *
+   * @resolves nsIPropertyBag { checked: boolean, user: string, pass: string, ok: boolean }
+   */
   Promise asyncPromptUsernameAndPassword(in BrowsingContext aBrowsingContext,
                                       in unsigned long modalType,
                                       in wstring aDialogTitle,
@@ -415,6 +518,14 @@ interface nsIPromptService : nsISupports
                          inout wstring aPassword,
                          in wstring aCheckMsg,
                          inout boolean aCheckState);
+  /**
+   * Like promptPassword, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   boolean promptPasswordBC(in BrowsingContext aBrowsingContext,
                            in unsigned long modalType,
                            in wstring aDialogTitle,
@@ -422,6 +533,13 @@ interface nsIPromptService : nsISupports
                            inout wstring aPassword,
                            in wstring aCheckMsg,
                            inout boolean aCheckState);
+  /**
+   * Async version of promptPasswordBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   *
+   * @resolves nsIPropertyBag { checked: boolean, pass: string, ok: boolean }
+   */
   Promise asyncPromptPassword(in BrowsingContext aBrowsingContext,
                            in unsigned long modalType,
                            in wstring aDialogTitle,
@@ -452,12 +570,27 @@ interface nsIPromptService : nsISupports
                  in wstring aText,
                  in Array<AString> aSelectList,
                  out long aOutSelection);
+  /**
+   * Like select, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   boolean selectBC(in BrowsingContext aBrowsingContext,
                    in unsigned long modalType,
                    in wstring aDialogTitle,
                    in wstring aText,
                    in Array<AString> aSelectList,
                    out long aOutSelection);
+  /**
+   * Async version of selectBC
+   *
+   * @return A promise which resolves when the prompt is dismissed.
+   *
+   * @resolves nsIPropertyBag { selected: int, ok: boolean }
+   */
   Promise asyncSelect(in BrowsingContext aBrowsingContext,
                    in unsigned long modalType,
                    in wstring aDialogTitle,
@@ -478,6 +611,14 @@ interface nsIPromptService : nsISupports
                      in nsIAuthInformation authInfo,
                      in wstring checkboxLabel,
                      inout boolean checkValue);
+  /**
+   * Like promptAuth, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   boolean promptAuthBC(in BrowsingContext aBrowsingContext,
                        in unsigned long modalType,
                        in nsIChannel aChannel,
@@ -485,7 +626,6 @@ interface nsIPromptService : nsISupports
                        in nsIAuthInformation authInfo,
                        in wstring checkboxLabel,
                        inout boolean checkValue);
-
   nsICancelable asyncPromptAuth(in mozIDOMWindowProxy aParent,
                                 in nsIChannel aChannel,
                                 in nsIAuthPromptCallback aCallback,
@@ -494,6 +634,14 @@ interface nsIPromptService : nsISupports
                                 in nsIAuthInformation authInfo,
                                 in wstring checkboxLabel,
                                 inout boolean checkValue);
+  /**
+   * Like asyncPromptAuth, but with a BrowsingContext as parent.
+   *
+   * @param aBrowsingContext
+   *        The browsing context the prompt should be opened for.
+   * @param modalType
+   *        Whether the prompt should be window, tab or content modal.
+   */
   nsICancelable asyncPromptAuthBC(in BrowsingContext aBrowsingContext,
                                   in unsigned long modalType,
                                   in nsIChannel aChannel,

toolkit/docs/index.rst

@@ -13,6 +13,7 @@ This is the nascent documentation of the Toolkit code that is shared across Fire
    components/featuregates/featuregates/index
    search/index
    components/normandy/normandy/index
+   components/prompts/prompts/index
    modules/subprocess/toolkit_modules/subprocess/index
    components/telemetry/index
    components/glean/index