Allow EmbedRoot to be called multiple times.

mojo/services/public/interfaces/view_manager/view_manager.mojom

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 import "mojo/services/public/interfaces/geometry/geometry.mojom"
 import "mojo/services/public/interfaces/input_events/input_events.mojom"
 import "mojo/services/public/interfaces/view_manager/view_manager_constants.mojom"
 
 module mojo.view_manager {
 
 struct NodeData {
   uint32 parent_id;
   uint32 node_id;
   uint32 view_id;
   mojo.Rect bounds;
   // TODO(sky): add visible.
 };
 
 enum ErrorCode {
   NONE,
   VALUE_IN_USE,
   ILLEGAL_ARGUMENT,
 };
 
-// ViewManagerInitService is responsible for launching the client that controls
-// the root node. mojo::view_manager returns an instance of this. All other
-// connections are established by the client this creates.
+// ViewManagerInitService is used to grant an application a connection to the
+// ViewManager by embedding it at an approriate Node.
 interface ViewManagerInitService {
+  // Embed the application @ |url| at an appropriate Node.
+  // The first time this method is called in the lifetime of a View Manager
+  // application instance, the "appropriate Node" is defined as being the
+  // service root Node.
+  // Subsequent times, implementation of this method is delegated to the
+  // application embedded at the service root Node. This application is
+  // typically referred to as the "window manager", and will have a specific
+  // definition of where within its Node hierarchy to embed an unparented URL.
   EmbedRoot(string url) => (bool success);
 };
 
 // Nodes and Views are identified by a uint32. The upper 16 bits are the
 // connection id, and the lower 16 the id assigned by the client.
 //
 // The root node is identified with a connection id of 0, and value of 1.
 [Client=ViewManagerClient]
 interface ViewManagerService {
   // Creates a new node with the specified id. It is up to the client to ensure
@@ skipping 147 matching lines @@
 
   // Invoked when focus shifts from one Node to another. |gained_focus_id| is
   // the id of the node that gained focus, or 0 if the node that gained focus is
   // not known to this connection. |lost_focus_id| is likewise the node that
   // lost focus.
   // TODO(beng): once aura is removed from the service, focus management should
   //             entirely move to the window manager and this method can be
   //             removed.
   OnFocusChanged(uint32 gained_focus_id, uint32 lost_focus_id);
 
-  // TODO(sky): move to separate interface when FIFO sorted out.
+  // TODO(sky): The following methods represent an interface between the view
+  //            manager and the application embedded at the service root node
+  //            (i.e. the window manager). These methods are not called on
+  //            any other clients. They should be moved to a separate interface
+  //            once support for derived FIFOs is landed.
 
+  // Requests the window manager create a "top level" node embedding |url|.
+  EmbedRoot(string url);
+
+  // Requests the view manager dispatch the event targeted at |view|.
   DispatchOnViewInputEvent(uint32 view, mojo.Event event);
 };
 
 }