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..4f2d60edabc5d8ec86f6fca564a04bfa0d27196e 100644
--- a/chrome/common/extensions/docs/templates/articles/messaging.html
+++ b/chrome/common/extensions/docs/templates/articles/messaging.html
@@ -75,11 +75,20 @@ 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> If none of the handlers call <code>sendResponse</code>, then the
+response callback is automatically invoked, unless one of the handlers returns
+true. Even if a message handler returned true, the callback may still be called
+automatically if the <code>sendResponse</code> callback is garbage-collected.
 
 
 <h2 id="connect">Long-lived connections</h2>
@@ -154,15 +163,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).

[Devlin, 2016/04/13 21:41:40]

nit: remove double-nested parens

[robwu, 2016/04/13 22:44:35]

Done.

+<br>
+Upon calling $(ref:tabs.connect), $(ref:runtime.connect) or
+$(ref:runtime.connectNative), a $(ref:runtime.Port Port) is created.
+This port is immediately usable can be used for sending messages to

[Devlin, 2016/04/13 21:41:40]

nit: usable *and* can

[robwu, 2016/04/13 22:44:34]

Done. s/is immediately usable can be used/can immediately be used/.

+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).

[Devlin, 2016/04/13 21:41:40]

"each *connected* frame", maybe?  (Ditto for below.)

[robwu, 2016/04/13 22:44:34]

This is about onConnect, not onMessage, so "each frame" is fine.

+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 either when there are no valid ports at the other

[Devlin, 2016/04/13 21:41:40]

remove "either"

[robwu, 2016/04/13 22:44:34]

Done.

+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>