Improve documentation of extension messaging

extensions/common/api/runtime.json

Index: extensions/common/api/runtime.json
diff --git a/extensions/common/api/runtime.json b/extensions/common/api/runtime.json
index d4a4e5980caf3b1d614e24f683de7e6d10751ebd..54190df3642f433add4d68cac684c688e4e051a4 100644
--- a/extensions/common/api/runtime.json
+++ b/extensions/common/api/runtime.json
@@ -14,17 +14,35 @@
         "id": "Port",
         "type": "object",
         "nocompile": true,
-        "description": "An object which allows two way communication with other pages.",
+        "description": "An object which allows two way communication with other pages. See <a href=\"messaging#connect\">Long-lived connections</a> for more information.",
         "properties": {
-          "name": {"type": "string"},
-          "disconnect": { "type": "function" },
-          "onDisconnect": { "$ref": "events.Event" },
-          "onMessage": { "$ref": "events.Event" },
-          "postMessage": {"type": "function"},
+          "name": {
+            "type": "string",
+            "description": "The name of the port, as specified in the call to $(ref:runtime.connect)."
+          },
+          "disconnect": {
+            "type": "function",
+            "description": "Immediately disconnect the port. Calling <code>disconnect()</code> on an already-disconnected port has no effect. When a port is disconnected, no new events will be dispatched to this port."
+          },
+          "onDisconnect": {
+            "$ref": "events.Event",
+            "description": "Fired when the port is disconnected from the other end(s). $(ref:runtime.lastError) may be set if the port was disconnected by an error. If the port is closed via $(ref:Port.disconnect disconnect), then this event is <em>only</em> fired on the other end. This event is fired at most once (see also <a href=\"messaging#port-lifetime\">Port lifetime</a>). The first and only parameter to the event handler is this disconnected port."
+          },
+          "onMessage": {
+            "$ref": "events.Event",
+            "description": "This event is fired when $(ref:Port.postMessage postMessage) is called by the other end of the port. The first parameter is the message, the second parameter is the port that received the message."
+          },
+          "postMessage": {
+            "type": "function",
+            "description": "Send a message to the other end of the port. If the port is disconnected, an error is thrown.",
+            "parameters": [
+              {"name": "message", "type": "any", "description": "The message to send. This object should be JSON-ifiable."}
+            ]
+          },
           "sender": {
             "$ref": "MessageSender",
             "optional": true,
-            "description": "This property will <b>only</b> be present on ports passed to onConnect/onConnectExternal listeners."
+            "description": "This property will <b>only</b> be present on ports passed to $(ref:runtime.onConnect onConnect) / $(ref:runtime.onConnectExternal onConnectExternal) listeners."
           }
         },
         "additionalProperties": { "type": "any"}
@@ -249,7 +267,7 @@
         "name": "connect",
         "type": "function",
         "nocompile": true,
-        "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 <a href=\"extensions/tabs#method-connect\">tabs.connect</a>.",
+        "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 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>."},
           {
@@ -264,14 +282,15 @@
         ],
         "returns": {
           "$ref": "Port",
-          "description": "Port through which messages can be sent and received. The port's $(ref:runtime.Port onDisconnect) event is fired if the extension/app does not exist. "
+          // TODO(robwu): This description should appear in the documentation, but the docserver does not render it.
+          "description": "Port through which messages can be sent and received. The port's $(ref:Port onDisconnect) event is fired if the extension/app does not exist. "
         }
       },
       {
         "name": "connectNative",
         "type": "function",
         "nocompile": true,
-        "description": "Connects to a native application in the host machine.",
+        "description": "Connects to a native application in the host machine. See <a href=\"nativeMessaging\">Native Messaging</a> for more information.",
         "parameters": [
           {
             "type": "string",
@@ -289,10 +308,10 @@
         "type": "function",
         "nocompile": true,
         "allowAmbiguousOptionalArguments": true,
-        "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 <a href=\"extensions/tabs#method-sendMessage\">tabs.sendMessage</a>.",
+        "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 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": "any", "name": "message", "description": "The message to send. This message should be a JSON-ifiable object." },
           {
             "type": "object",
             "name": "options",
@@ -467,7 +486,7 @@
         "options": {
           "unmanaged": true
         },
-        "description": "Fired when a connection is made from either an extension process or a content script.",
+        "description": "Fired when a connection is made from either an extension process or a content script (by $(ref:runtime.connect)).",
         "parameters": [
           {"$ref": "Port", "name": "port"}
         ]
@@ -476,7 +495,7 @@
         "name": "onConnectExternal",
         "type": "function",
         "nocompile": true,
-        "description": "Fired when a connection is made from another extension.",
+        "description": "Fired when a connection is made from another extension (by $(ref:runtime.connect)).",
         "parameters": [
           {"$ref": "Port", "name": "port"}
         ]
@@ -488,11 +507,11 @@
         "options": {
           "unmanaged": true
         },
-        "description": "Fired when a message is sent from either an extension process or a content script.",
+        "description": "Fired when a message is sent from either an extension process (by $(ref:runtime.sendMessage)) or a content script (by $(ref:tabs.sendMessage)).",
         "parameters": [
           {"name": "message", "type": "any", "optional": true, "description": "The message sent by the calling script."},
           {"name": "sender", "$ref": "MessageSender" },
-          {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." }
+          {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, <strong>unless you return true</strong> from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." }
         ],
         "returns": {
           "type": "boolean",
@@ -504,11 +523,11 @@
         "name": "onMessageExternal",
         "type": "function",
         "nocompile": true,
-        "description": "Fired when a message is sent from another extension/app. Cannot be used in a content script.",
+        "description": "Fired when a message is sent from another extension/app (by $(ref:runtime.sendMessage)). Cannot be used in a content script.",
         "parameters": [
           {"name": "message", "type": "any", "optional": true, "description": "The message sent by the calling script."},
           {"name": "sender", "$ref": "MessageSender" },
-          {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." }
+          {"name": "sendResponse", "type": "function", "description": "Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one <code>onMessage</code> listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, <strong>unless you return true</strong> from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until <code>sendResponse</code> is called)." }
         ],
         "returns": {
           "type": "boolean",