1 files changed, 140 insertions, 0 deletions
diff --git a/tools/addon-sdk-1.5/packages/api-utils/docs/tab-browser.md b/tools/addon-sdk-1.5/packages/api-utils/docs/tab-browser.md
new file mode 100644
index 0000000..295fcc7
--- /dev/null
+++ b/tools/addon-sdk-1.5/packages/api-utils/docs/tab-browser.md
@@ -0,0 +1,140 @@
+<!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+
+<!-- contributed by Dietrich Ayala [dietrich@mozilla.com]  -->
+
+The `tab-browser` module is a low-level API that provides privileged
+access to browser tab events and actions.
+
+Introduction
+------------
+
+The `tab-browser` module contains helpers for tracking tabbrowser elements
+and tabs, as well as a few utilities for actions such as opening a new
+tab, and catching all tab content loads.
+
+This is a low-level API that has full privileges, and is intended to be used
+by SDK internal modules. If you just need easy access to tab events for your
+add-on, use the Tabs module (JEP 110).
+
+<api name="activeTab">
+@property {element}
+The XUL tab element of the currently active tab.
+</api>
+
+<api name="addTab">
+@function
+Adds a new tab.
+
+**Example**
+
+    var tabBrowser = require("tab-browser");
+    tabBrowser.addTab("http://google.com");
+
+    var tabBrowser = require("tab-browser");
+    tabBrowser.addTab("http://google.com", {
+      inBackground: true
+    });
+
+    var tabBrowser = require("tab-browser");
+    tabBrowser.addTab("http://google.com", {
+      inNewWindow: true,
+      onLoad: function(tab) {
+        console.log("tab is open.");
+      }
+    });
+
+@returns {element}
+The XUL tab element of the newly created tab.
+
+@param URL {string}
+The URL to be opened in the new tab.
+
+@param options {object}
+Options for how and where to open the new tab.
+
+@prop [inNewWindow] {boolean}
+An optional parameter whose key can be set in `options`.
+If true, the tab is opened in a new window. Default is false.
+
+@prop [inBackground] {boolean}
+An optional parameter whose key can be set in `options`.
+If true, the tab is opened adjacent to the active tab, but not
+switched to. Default is false.
+
+@prop [onLoad] {function}
+An optional parameter whose key can be set in `options`.
+A callback function that is called once the tab has loaded.
+The XUL element for the tab is passed as a parameter to
+this function.
+</api>
+
+<api name="Tracker">
+@function
+Register a delegate object to be notified when tabbrowsers are created
+and destroyed.
+
+The onTrack method will be called once per pre-existing tabbrowser, upon
+tracker registration.
+
+**Example**
+
+    var tabBrowser = require("tab-browser");
+    let tracker = {
+      onTrack: function(tabbrowser) {
+        console.log("A new tabbrowser is being tracked.");
+      },
+      onUntrack: function(tabbrowser) {
+        console.log("A tabbrowser is no longer being tracked.");
+      }
+    };
+    tabBrowser.Tracker(tracker);
+
+@param delegate {object}
+Delegate object to be notified each time a tabbrowser is created or destroyed.
+The object should contain the following methods:
+
+@prop [onTrack] {function}
+Method of delegate that is called when a new tabbrowser starts to be tracked.
+The tabbrowser element is passed as a parameter to this method.
+
+@prop [onUntrack] {function}
+Method of delegate that is called when a tabbrowser stops being tracked.
+The tabbrowser element is passed as a parameter to this method.
+</api>
+
+<api name="TabTracker">
+@function
+Register a delegate object to be notified when tabs are opened and closed.
+
+
+The onTrack method will be called once per pre-existing tab, upon
+tracker registration.
+
+**Example**
+
+    var tabBrowser = require("tab-browser");
+    let tracker = {
+      onTrack: function(tab) {
+        console.log("A new tab is being tracked.");
+      },
+      onUntrack: function(tab) {
+        console.log("A tab is no longer being tracked.");
+      }
+    };
+    tabBrowser.TabTracker(tracker);
+
+@param delegate {object}
+Delegate object to be notified each time a tab is opened or closed.
+The object should contain the following methods:
+
+@prop [onTrack] {function}
+Method of delegate that is called when a new tab starts to be tracked.
+The tab element is passed as a parameter to this method.
+
+@prop [onUntrack] {function}
+Method of delegate that is called when a tab stops being tracked.
+The tab element is passed as a parameter to this method.
+</api>
+