Add chrome.extension to extension_api.json and docs

chrome/common/extensions/api/extension_api.json

 [
   {
+    "namespace": "extension",
+    "types": [
+      {
+        "id": "Port",
+        "type": "object",
+        "properties": {
+          "name": {"type": "string"},
+          "onDisconnect": {"type": "object"},
+          "onMessage": {"type": "object"},
+          "postMessage": {"type": "function"}
+        }
+      }
+    ],
+    "functions": [
+      {
+        "name": "connect",
+        "type": "function",
+        "description": "Attempts to connect to other listeners within the extension (listeners may be toolstrips or the extension's background page). This is primarily useful for content scripts connecting to their extension processes. Extensions may connect to content scripts embedded in tabs via <a href='broken'><var>chrome.tabs.connectToTab</var></a>.",
+        "parameters": [
+          {
+            "name": "name",
+            "type": "string",
+            "description": "Will be passed into onConnect for extension processes that are listening for the connection event.",
+            "optional": true
+          }
+        ],
+        "returns": {
+          "$ref": "Port",
+          "description": "Port through which messages can be sent and received with the extension."
+        }
+      }
+    ],
+    "events": [
+      {
+        "name": "onConnect",
+        "type": "function",
+        "description": "Fired when a connection is made from either an extension process or a content script.",
+        "parameters": [
+          {"$ref": "Port", "name": "port"}
+        ]
+      }
+    ]
+  },
+  {
     "namespace": "self",
     "types": [
     ],
     "functions": [
       {
         "name": "getViews",
         "type": "function",
         "description": "Returns an array of the global JavaScript objects for each of the views running inside the current extension. This includes toolstrips, background pages, and tabs.",
         "parameters": [],
         "returns": {
@@ skipping 191 matching lines @@
         "type": "object",
         "properties": {
           "id": {"type": "integer", "minimum": 0},
           "index": {"type": "integer", "minimum": 0},
           "windowId": {"type": "integer", "minimum": 0},
           "selected": {"type": "boolean"},
           "url": {"type": "string"},
           "title": {"type": "string", "optional": true},
           "favIconUrl": {"type": "string", "optional": true}
         }
-      },
-      {
-        "id": "Port",
-        "type": "object",
-        "properties": {
-          "name": {"type": "string"},
-          "onDisconnect": {"type": "object"},
-          "onMessage": {"type": "object"}
-        }
       }
     ],
     "functions": [
       {
         "name": "get",
         "type": "function",
         "description": "",
         "parameters": [
           {"type": "integer", "name": "tabId", "minimum": 0},
           {
@@ skipping 18 matching lines @@
           "$ref": "Port"
         }
       },
       {
         "name": "getSelected",
         "type": "function",
         "description": "",
         "parameters": [
           {"type": "integer", "name": "windowId", "minimum": 0, "optional": true},
           {
-            "type": "function", 
+            "type": "function",
             "name": "callback",
             "parameters": [
               {"name": "tab", "$ref": "Tab"}
             ]
           }
         ]
       },
       {
         "name": "getAllInWindow",
         "type": "function",
         "description": "",
         "parameters": [
           {"type": "integer", "name": "windowId", "minimum": 0, "optional": true},
           {
-            "type": "function", 
+            "type": "function",
             "name": "callback",
             "parameters": [
               {"name": "tabs", "type": "array", "items": { "$ref": "Tab" } }
             ]
           }
         ]
       },
       {
         "name": "create",
         "type": "function",
@@ skipping 243 matching lines @@
         "name": "get",
         "type": "function",
         "description": "Retrieves the specified BookmarkTreeNode(s).",
         "parameters": [
           {
             "name": "idOrIdList",
             "description": "A single string-valued id, or an array of string-valued ids",
             "choices": [
               {"type": "string"},
               {"type": "array", "items": {"type": "string"}, "minItems": 1}
-            ] 
+            ]
           },
           {
-            "type": "function", 
+            "type": "function",
             "name": "callback",
             "parameters": [
               {"name": "results", "type": "array", "items": { "$ref": "BookmarkTreeNode"} }
             ]
           }
         ]
       },
       {
         "name": "getChildren",
         "type": "function",
         "description": "Retrieves the children of the specified BookmarkTreeNode id.",
         "parameters": [
           {"type": "string", "name": "id"},
           {
             "type": "function", 
             "name": "callback",
             "parameters": [
               {"name": "results", "type": "array", "items": { "$ref": "BookmarkTreeNode"} }
             ]
           }
         ]
       },
       {
         "name": "getTree",
         "type": "function",
         "description": "Retrieves the entire Bookmarks hierarchy.",
         "parameters": [
           {
-            "type": "function", 
+            "type": "function",
             "name": "callback",
             "parameters": [
               {"name": "results", "type": "array", "items": { "$ref": "BookmarkTreeNode"} }
             ]
           }
         ]
       },
       {
         "name": "search",
         "type": "function",
         "description": "Seaches for BookmarkTreeNodes matching the given query.",
         "parameters": [
           {"type": "string", "name": "query"},
           {
-            "type": "function", 
+            "type": "function",
             "name": "callback",
             "parameters": [
               {"name": "results", "type": "array", "items": { "$ref": "BookmarkTreeNode"} }
             ]
           }
         ]
       },
       {
         "name": "create",
         "type": "function",
         "description": "",
         "parameters": [
           {
             "type": "object",
             "name": "bookmark",
             "properties": {
               "parentId": {"type": "string"},
               "index": {"type": "integer", "minimum": 0, "optional": true},
               "title": {"type": "string", "optional": true},
               "url": {"type": "string", "optional": true}
             }
           },
           {
-            "type": "function", 
+            "type": "function",
             "name": "callback",
             "optional": true,
             "parameters": [
               {"name": "result", "$ref": "BookmarkTreeNode" }
             ]
           }
         ]
       },
       {
         "name": "move",
@@ skipping 148 matching lines @@
         "description": "",
         "parameters": [
           {"type": "string", "name": "url", "optional": true},
           {"type": "function", "name": "callback", "optional": true, "parameters": []}
         ]
       }
     ],
     "events": []
   }
 ]