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..08cbcc7d8541d2465c3f0665dc04e4f4f81563cf 100644
--- a/chrome/common/extensions/docs/templates/articles/messaging.html
+++ b/chrome/common/extensions/docs/templates/articles/messaging.html
@@ -75,11 +75,18 @@ chrome.runtime.onMessage.addListener(
   });
 </pre>
 
+In the above example, <code>sendResponse</code> was called synchronously.

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

Why is this important?

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

I've added another sentence; see also my reply below.

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

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

I don't know that we should add this to the documentation.  It strikes me as an
implementation detail, and, if we do, it means that we're more locked into that
behavior.  I think I'd rather not document the cases in which sendResponse is
called synchronously vs asynchronously - I don't think it's something that
developers should be relying on.

WDYT?

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

Sending messages within an extension is quite important, so we should commit to
a stable API that behaves in a sane way. Whether and when the response callback
is invoked is quite important in practice, so even if we don't document it,
people will do trial-and-error and assume that that is the intended API.
Synchronous vs asynchronous invocation of sendResponse is highly relevant for
the users of chrome.runtime.onMessage. It is the most frequently asked question
about Chrome Extensions on Stack Overflow
(https://stackoverflow.com/questions/20077487/chrome-extension-message-passing...).

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

Ah, I see what you're trying to say with this comment (I thought you were trying
to document whether or not sendResponse would be called synchronously by chrome
if a developer didn't return true).  Okay, this makes more sense now.  I'd still
like to tweak it a bit to make it more clear what the intent is.  What about
something like:

The sendResponse 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.

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

Nice wording, I've copied it verbatim.

+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 +161,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 is immediately usable and messages can be used to send messages to

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

rephrase this - "... usable and messages can be used to send messages" doesn't
quite make sense. :)

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

Done.

+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 may be fired

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

onConnect *event*?  Also maybe linkify?

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

Done.

onConnect was already linkified in the previous sentence. Linking it again is a
bit too much.

+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
+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 fired at the other ports.
+</ul>
 
 
 <h2 id="external">Cross-extension messaging</h2>