--- a/testing/marionette/proxy.js
+++ b/testing/marionette/proxy.js
@@ -59,18 +59,19 @@ proxy.toListener = function(mmFn, sendAs
   return new Proxy(sender, ownPriorityGetterTrap);
 };
 
 /**
  * Provides a transparent interface between chrome- and content space.
  *
  * The AsyncMessageChannel is an abstraction of the message manager
  * IPC architecture allowing calls to be made to any registered message
- * listener in Marionette.  The {@code #send(...)} method returns a promise
- * that gets resolved when the message handler calls {@code .reply(...)}.
+ * listener in Marionette.  The <code>#send(...)</code> method
+ * returns a promise that gets resolved when the message handler calls
+ * <code>.reply(...)</code>.
  */
 proxy.AsyncMessageChannel = class {
   constructor(mmFn, sendAsyncFn, browserFn) {
     this.mmFn_ = mmFn;
     this.sendAsync = sendAsyncFn;
     this.browserFn_ = browserFn;
 
     // TODO(ato): Bug 1242595
@@ -90,23 +91,25 @@ proxy.AsyncMessageChannel = class {
   }
 
   /**
    * Send a message across the channel.  The name of the function to
    * call must be registered as a message listener.
    *
    * Usage:
    *
+   * <pre><code>
    *     let channel = new AsyncMessageChannel(
    *         messageManager, sendAsyncMessage.bind(this));
-   *     let rv = yield channel.send("remoteFunction", ["argument"]);
+   *     let rv = await channel.send("remoteFunction", ["argument"]);
+   * </code></pre>
    *
    * @param {string} name
    *     Function to call in the listener, e.g. for the message listener
-   *     "Marionette:foo8", use "foo".
+   *     <tt>Marionette:foo8</tt>, use <tt>foo</tt>.
    * @param {Array.<?>=} args
    *     Argument list to pass the function. If args has a single entry
    *     that is an object, we assume it's an old style dispatch, and
    *     the object will passed literally.
    *
    * @return {Promise}
    *     A promise that resolves to the result of the command.
    * @throws {TypeError}
@@ -213,18 +216,18 @@ proxy.AsyncMessageChannel = class {
         node.removeEventListener("TabClose", this.closeHandler);
       }
     }
   }
 
   /**
    * Reply to an asynchronous request.
    *
-   * Passing an WebDriverError prototype will cause the receiving channel
-   * to throw this error.
+   * Passing an {@link WebDriverError} prototype will cause the receiving
+   * channel to throw this error.
    *
    * Usage:
    *
    * <pre><code>
    *     let channel = proxy.AsyncMessageChannel(
    *         messageManager, sendAsyncMessage.bind(this));
    *
    *     // throws in requester:
@@ -338,29 +341,29 @@ proxy.toChromeAsync = function(frameMess
 /**
  * Sends asynchronous RPC messages to chrome space using a frame's
  * sendAsyncMessage (nsIAsyncMessageSender) function.
  *
  * Example on how to use from a frame content script:
  *
  *     let sender = new AsyncChromeSender(messageManager);
  *     let promise = sender.send("runEmulatorCmd", "my command");
- *     let rv = yield promise;
+ *     let rv = await promise;
  */
 class AsyncChromeSender {
   constructor(frameMessageManager) {
     this.mm = frameMessageManager;
   }
 
   /**
    * Call registered function in chrome context.
    *
    * @param {string} name
-   *     Function to call in the chrome, e.g. for "Marionette:foo", use
-   *     "foo".
+   *     Function to call in the chrome, e.g. for <tt>Marionette:foo</tt>,
+   *     use <tt>foo</tt>.
    * @param {*} args
    *     Argument list to pass the function.  Must be JSON serialisable.
    *
    * @return {Promise}
    *     A promise that resolves to the value sent back.
    */
   send(name, args) {
     let uuid = uuidgen.generateUUID().toString();
@@ -393,41 +396,45 @@ class AsyncChromeSender {
     return proxy;
   }
 }
 
 /**
  * Creates a transparent interface from the content- to the chrome context.
  *
  * Calls to this object will be proxied via the frame's sendSyncMessage
- * (nsISyncMessageSender) function.  Since the message is synchronous,
- * the return value is presented as a return value.
+ * ({@link nsISyncMessageSender}) function.  Since the message is
+ * synchronous, the return value is presented as a return value.
  *
  * Example on how to use from a frame content script:
  *
+ * <pre><code>
  *     let chrome = proxy.toChrome(sendSyncMessage.bind(this));
  *     let cookie = chrome.getCookie("foo");
+ * </code></pre>
  *
  * @param {nsISyncMessageSender} sendSyncMessageFn
  *     The frame message manager's sendSyncMessage function.
  */
 proxy.toChrome = function(sendSyncMessageFn) {
   let sender = new proxy.SyncChromeSender(sendSyncMessageFn);
   return new Proxy(sender, ownPriorityGetterTrap);
 };
 
 /**
  * The SyncChromeSender sends synchronous RPC messages to the chrome
- * context, using a frame's sendSyncMessage (nsISyncMessageSender)
+ * context, using a frame's sendSyncMessage ({@link nsISyncMessageSender})
  * function.
  *
  * Example on how to use from a frame content script:
  *
+ * <pre><code>
  *     let sender = new SyncChromeSender(sendSyncMessage.bind(this));
  *     let res = sender.send("addCookie", cookie);
+ * </code></pre>
  */
 proxy.SyncChromeSender = class {
   constructor(sendSyncMessage) {
     this.sendSyncMessage_ = sendSyncMessage;
   }
 
   send(func, args) {
     let name = "Marionette:" + func.toString();