Improve documentation of extension messaging

extensions/common/api/runtime.json

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Note: Many of these functions and events are implemented by hand and should
 // not elicit any code generation from the schema compiler. These items are
 // marked "nocompile."
 [
   {
     "namespace": "runtime",
     "description": "Use the <code>chrome.runtime</code> API to retrieve the background page, return details about the manifest, and listen for and respond to events in the app or extension lifecycle. You can also use this API to convert the relative path of URLs to fully-qualified URLs.",
     "types": [
       {
         "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 <em>new</em> events are generated any more on this port. If <code>disconnect()</code> was called while dispatching an $(ref:Port.onMessage onMessage) event, then the existing handlers still continue to be fired for that event."

[Devlin, 2016/04/13 20:15:33]

remove "any more"

[Devlin, 2016/04/13 20:15:33]

Here, too, I worry that we're getting too much into the implementation.  I'd
rather not specify what happens to events in-flight.

[robwu, 2016/04/13 21:03:05]

Done.

[robwu, 2016/04/13 21:03:05]

Done.

+          },
+          "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"}
       },
       {
         "id": "MessageSender",
         "type": "object",
         "nocompile": true,
         "description": "An object containing information about the script context that sent a message or request.",
         "properties": {
@@ skipping 204 matching lines @@
       {
         "name": "restart",
         "description": "Restart the ChromeOS device when the app runs in kiosk mode. Otherwise, it's no-op.",
         "type": "function",
         "parameters": []
       },
       {
         "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>."},
           {
             "type": "object",
             "name": "connectInfo",
             "properties": {
               "name": { "type": "string", "optional": true, "description": "Will be passed into onConnect for processes that are listening for the connection event." },
               "includeTlsChannelId": { "type": "boolean", "optional": true, "description": "Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event." }
             },
             "optional": true
           }
         ],
         "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",
             "name": "application",
             "description": "The name of the registered application to connect to."
           }
         ],
         "returns": {
           "$ref": "Port",
           "description": "Port through which messages can be sent and received with the application"
         }
       },
       {
         "name": "sendMessage",
         "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 JSON-ifiable object." },
           {
             "type": "object",
             "name": "options",
             "properties": {
               "includeTlsChannelId": { "type": "boolean", "optional": true, "description": "Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event." }
             },
             "optional": true
           },
           {
             "type": "function",
@@ skipping 154 matching lines @@
         "deprecated": "Please use $(ref:runtime.onRestartRequired).",
         "parameters": []
       },
       {
         "name": "onConnect",
         "type": "function",
         "nocompile": true,
         "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"}
         ]
       },
       {
         "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"}
         ]
       },
       {
         "name": "onMessage",
         "type": "function",
         "nocompile": true,
         "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",
           "optional": true,
           "description": "Return true from the event listener if you wish to call <code>sendResponse</code> after the event listener returns."
         }
       },
       {
         "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",
           "optional": true,
           "description": "Return true from the event listener if you wish to call <code>sendResponse</code> after the event listener returns."
         }
       },
       {
         "name": "onRestartRequired",
         "type": "function",
         "description": "Fired when an app or the device that it runs on needs to be restarted. The app should close all its windows at its earliest convenient time to let the restart to happen. If the app does nothing, a restart will be enforced after a 24-hour grace period has passed. Currently, this event is only fired for Chrome OS kiosk apps.",
         "parameters": [
           {
             "$ref": "OnRestartRequiredReason",
             "name": "reason",
             "description": "The reason that the event is being dispatched."
           }
         ]
       }
     ]
   }
 ]