Clarify runtime.connect and runtime.sendMessage docs.

BUG=326250
R=mkearney@chromium.org
TBR=yoz@chromium.org

Review URL: https://codereview.chromium.org/134533004

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@245292 0039d316-1c4b-4281-b951-d872f2087c98

chrome/common/extensions/api/runtime.json

@@ -172,9 +172,9 @@
         "name": "connect",
         "type": "function",
         "nocompile": true,
-        "description": "Attempts to connect to other listeners within the extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via $ref:tabs.connect.",
+        "description": "Attempts to connect to connect listeners within an extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and <a href=\"manifest/externally_connectable.html\">web messaging</a>. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via $ref:tabs.connect.",
         "parameters": [
-          {"type": "string", "name": "extensionId", "optional": true, "description": "The ID of the extension/app you want to connect to. If omitted, default is your own extension."},
+          {"type": "string", "name": "extensionId", "optional": true, "description": "The ID of the extension or app to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for <a href=\"manifest/externally_connectable.html\">web messaging</a>."},
           {
             "type": "object",
             "name": "connectInfo",
@@ -212,9 +212,9 @@
         "type": "function",
         "nocompile": true,
         "allowAmbiguousOptionalArguments": true,
-        "description": "Sends a single message to onMessage event listeners within the extension (or another extension/app). Similar to chrome.runtime.connect, but only sends a single message with an optional response. The $ref:runtime.onMessage event is fired in each extension page of the extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use $ref:tabs.sendMessage.",
+        "description": "Sends a single message to event listeners within your extension/app or a different extension/app. Similar to $ref:runtime.connect but only sends a single message, with an optional response. If sending to your extension, the $ref:runtime.onMessage event will be fired in each page, or $ref:runtime.onMessageExternal, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use $ref:tabs.sendMessage.",
         "parameters": [
-          {"type": "string", "name": "extensionId", "optional": true, "description": "The extension ID of the extension you want to connect to. If omitted, default is your own extension."},
+          {"type": "string", "name": "extensionId", "optional": true, "description": "The ID of the extension/app to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for <a href=\"manifest/externally_connectable.html\">web messaging</a>."},
           { "type": "any", "name": "message" },
           {
             "type": "object",