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

mojo/shell/public/cpp/shell.h

Index: mojo/shell/public/cpp/shell.h
diff --git a/mojo/shell/public/cpp/shell.h b/mojo/shell/public/cpp/shell.h
index 00e4605bb9197a823069cec1a6ec5f4241e8543c..151ff3ef0931af2990c5ec4999c3a64add22aa17 100644
--- a/mojo/shell/public/cpp/shell.h
+++ b/mojo/shell/public/cpp/shell.h
@@ -16,6 +16,9 @@ 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 {