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.

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