Improve documentation of extension messaging

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

Index: chrome/common/extensions/docs/templates/articles/messaging.html
diff --git a/chrome/common/extensions/docs/templates/articles/messaging.html b/chrome/common/extensions/docs/templates/articles/messaging.html
index 782c3a454d3b0f89964471308b524837f9953b67..b290d3275069930c87b9e8354dfa0d6ad1cb9eba 100644
--- a/chrome/common/extensions/docs/templates/articles/messaging.html
+++ b/chrome/common/extensions/docs/templates/articles/messaging.html
@@ -75,11 +75,21 @@ chrome.runtime.onMessage.addListener(
   });
 </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>
@@ -154,15 +164,46 @@ chrome.runtime.onConnect.addListener(function(port) {
 });
 </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>