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

mojo/shell/public/cpp/shell.h

 // Copyright 2016 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_SHELL_H_
 #define MOJO_SHELL_PUBLIC_CPP_SHELL_H_
 
 #include "mojo/shell/public/cpp/app_lifetime_helper.h"
 #include "mojo/shell/public/cpp/connection.h"
 #include "mojo/shell/public/interfaces/shell.mojom.h"
 #include "mojo/shell/public/interfaces/shell_client.mojom.h"
 
 namespace mojo {
 
 shell::mojom::CapabilityFilterPtr CreatePermissiveCapabilityFilter();
 
 using ShellClientRequest = InterfaceRequest<shell::mojom::ShellClient>;
 
+// An interface that encapsulates the Mojo Shell's broker interface by which
+// connections between applications are established. Implemented by
+// ShellConnection, this is the primary interface exposed to clients.
 class Shell {
  public:
   class ConnectParams {
    public:
     explicit ConnectParams(const std::string& url);
     explicit ConnectParams(URLRequestPtr request);
     ~ConnectParams();
 
     URLRequestPtr TakeRequest() { return std::move(request_); }
     shell::mojom::CapabilityFilterPtr TakeFilter() {
@@ skipping 37 matching lines @@
 
   // Create an object that can be used to refcount the lifetime of the
   // application. The returned object may be cloned, and when the refcount falls
   // to zero Quit() is called.
   virtual scoped_ptr<AppRefCount> CreateAppRefCount() = 0;
 };
 
 }  // namespace mojo
 
 #endif  // MOJO_SHELL_PUBLIC_CPP_SHELL_H_