Improve documentation of extension messaging

chrome/common/extensions/docs/templates/articles/messaging.html

 <h1>Message Passing</h1>
 
 
 <p>
 Since content scripts run in the context of a web page and not the extension,
 they often need some way of communicating with the rest of the extension. For
 example, an RSS reader extension might use content scripts to detect the
 presence of an RSS feed on a page, then notify the background page in order to
 display a page action icon for that page.
 
@@ skipping 57 matching lines @@
 chrome.runtime.onMessage.addListener(
   function(request, sender, sendResponse) {
     console.log(sender.tab ?
                 "from a content script:" + sender.tab.url :
                 "from the extension");
     if (request.greeting == "hello")
       sendResponse({farewell: "goodbye"});
   });
 </pre>
 
+In the above example, <code>sendResponse</code> was called synchronously.
+If you want to asynchronously use <code>sendResponse</code>, add
+<code>return true;</code> to the <code>onMessage</code> event handler.
+
 <p class="note">
 <b>Note:</b> If multiple pages are listening for onMessage events, only the
 first to call sendResponse() for a particular event will succeed in sending the
 response. All other responses to that event will be ignored.
-</p>
+
+<p class="note">
+<b>Note:</b> The <code>sendResponse</code> callback is only valid if used
+synchronously, or if the event handler returns <code>true</code> to indicate
+that it will respond asynchronously. The <code>sendMessage</code> function's
+callback will be invoked automatically if no handlers return true or if the
+<code>sendResponse</code> callback is garbage-collected.
 
 
 <h2 id="connect">Long-lived connections</h2>
 <p>
 Sometimes it's useful to have a conversation that lasts longer than a single
 request and response. In this case, you can open a long-lived channel from
 your content script to an extension page
 {{^is_apps}}
 , or vice versa,
 {{/is_apps}}
@@ skipping 54 matching lines @@
     if (msg.joke == "Knock knock")
       port.postMessage({question: "Who's there?"});
     else if (msg.answer == "Madame")
       port.postMessage({question: "Madame who?"});
     else if (msg.answer == "Madame... Bovary")
       port.postMessage({question: "I don't get it."});
   });
 });
 </pre>
 
+<h3 id="port-lifetime">Port lifetime</h3>
+<p>
+Ports are designed as a two-way communication method between different parts of
+the extension, where a (top-level) frame is viewed as the smallest part.
+<br>
+Upon calling $(ref:tabs.connect), $(ref:runtime.connect) or
+$(ref:runtime.connectNative), a $(ref:runtime.Port Port) is created.
+This port can immediately be used for sending messages to the other end via
+$(ref:runtime.Port.postMessage postMessage).
+
+<p>
+If there are multiple frames in a tab, calling $(ref:tabs.connect) results in
+multiple invocations of the $(ref:runtime.onConnect) event
+(once for each frame in the tab).
+Similarly, if $(ref:runtime.connect) is used, then the onConnect event
+may be fired multiple times (once for every frame in the extension process).
+
 <p>
 You may want to find out when a connection is closed, for example if you are
 maintaining separate state for each open port. For this you can listen to the
 $(ref:runtime.Port.onDisconnect)
-event. This event is fired either when the other side of the channel manually
-calls
-$(ref:runtime.Port.disconnect), or when the page
-containing the port is unloaded (for example if the tab is navigated).
-onDisconnect is guaranteed to be fired only once for any given port.
+event. This event is fired when there are no valid ports at the other side of
+the channel. This happens in the following situations:
+<ul>
+  <li>
+    There are no listeners for $(ref:runtime.onConnect) at the other end.
+  <li>
+    The tab containing the port is unloaded (e.g. if the tab is navigated).
+  <li>
+    The frame from where <code>connect</code> was called has unloaded.
+  <li>
+    All frames that received the port (via $(ref:runtime.onConnect)) have
+    unloaded.
+  <li>
+    $(ref:runtime.Port.disconnect) is called by <em>the other end</em>.
+    Note that if a <code>connect</code> call results in multiple ports at the
+    receiver's end, and <code>disconnect()</code> is called on any of these
+    ports, then the <code>onDisconnect</code> event is only fired at the port
+    of the sender, and not at the other ports.
+</ul>
 
 
 <h2 id="external">Cross-extension messaging</h2>
 <p>
 In addition to sending messages between different components in your
 extension, you can use the messaging API to communicate with other extensions.
 This lets you expose a public API that other extensions can take advantage of.
 
 <p>
 Listening for incoming requests and connections is similar to the internal
@@ skipping 156 matching lines @@
 
 <p>
 You can find simple examples of communication via messages in the
 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/messaging/">examples/api/messaging</a>
 directory.
 The <a href="nativeMessaging#examples">native messaging sample</a> demonstrates
 how a Chrome app can communicate with a native app.
 For more examples and for help in viewing the source code, see
 <a href="samples">Samples</a>.
 </p>