Revise comments on various Shell interfaces. Make some methods private on ShellConnection.

mojo/shell/public/cpp/connection.h

 // 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.
 
 #ifndef MOJO_SHELL_PUBLIC_CPP_CONNECTION_H_
 #define MOJO_SHELL_PUBLIC_CPP_CONNECTION_H_
 
 #include <stdint.h>
 
 #include <string>
 #include <utility>
 
 #include "base/memory/weak_ptr.h"
 #include "mojo/shell/public/cpp/lib/interface_factory_binder.h"
 #include "mojo/shell/public/interfaces/interface_provider.mojom.h"
 
 namespace mojo {
 
 class InterfaceBinder;
 
 // Represents a connection to another application. An instance of this class is
-// passed to ShellClient's AcceptConnection() method each
-// time a connection is made to this app.
+// returned from Shell's ConnectToApplication(), and passed to ShellClient's
+// AcceptConnection() each time an incoming connection is received.
 //
 // To use, define a class that implements your specific interface. Then
 // implement an InterfaceFactory<Foo> that binds instances of FooImpl to
 // InterfaceRequest<Foo>s and register that on the connection like this:
 //
 //   connection->AddInterface(&factory);
 //
 // Or, if you have multiple factories implemented by the same type, explicitly
 // specify the interface to register the factory for:
 //
 //   connection->AddInterface<Foo>(&my_foo_and_bar_factory_);
 //   connection->AddInterface<Bar>(&my_foo_and_bar_factory_);
 //
 // The InterfaceFactory must outlive the Connection.
 //
-// Additionally you specify a InterfaceBinder. If a InterfaceBinder has
-// been set and an InterfaceFactory has not been registered for the interface
-// request, than the interface request is sent to the InterfaceBinder.
+// Additionally you may specify a default InterfaceBinder to handle requests for
+// interfaces unhandled by any registered InterfaceFactory. Just as with
+// InterfaceFactory, the default InterfaceBinder supplied must outlive
+// Connection.
 //
-// Just as with InterfaceFactory, InterfaceBinder must outlive Connection.
-//
-// An Connection's lifetime is managed by an ShellConnection. To close a
-// connection, call CloseConnection which will destroy this object.
+// A Connection returned via Shell::ConnectToApplication() is owned by the
+// caller.
+// An Connection received via AcceptConnection is owned by the ShellConnection.
+// To close a connection, call CloseConnection which will destroy this object.
 class Connection {
  public:
   virtual ~Connection() {}
 
   class TestApi {
    public:
     explicit TestApi(Connection* connection) : connection_(connection) {}
     base::WeakPtr<Connection> GetWeakPtr() {
       return connection_->GetWeakPtr();
     }
@@ skipping 81 matching lines @@
   // some filtering policy preventing this interface from being exposed).
    virtual bool SetInterfaceBinderForName(InterfaceBinder* binder,
                                           const std::string& name) = 0;
 
   virtual base::WeakPtr<Connection> GetWeakPtr() = 0;
 };
 
 }  // namespace mojo
 
 #endif  // MOJO_SHELL_PUBLIC_CPP_CONNECTION_H_