Update comment for BrokerProcess constructor

Adds a discussion about the need for client-side checks, and
corrects the description of parameters to match the current
code.

Change-Id: I6687c4c6ce12296ccb2ebfebe98e46a75afb8d64
Reviewed-on: https://chromium-review.googlesource.com/797372Reviewed-by: Robert Sesek <rsesek@chromium.org>
Commit-Queue: Tom Sepez <tsepez@chromium.org>
Cr-Commit-Position: refs/heads/master@{#520195}

sandbox/linux/syscall_broker/broker_process.h

@@ -37,14 +37,17 @@ class BrokerFilePermission;
 class SANDBOX_EXPORT BrokerProcess {
  public:
   // |denied_errno| is the error code returned when methods such as Open()
-  // or Access() are invoked on a file which is not in the whitelist. EACCESS
-  // would be a typical value.
-  // |allowed_r_files| and |allowed_w_files| are white lists of files that can
-  // be opened later via the Open() API, respectively for reading and writing.
-  // A file available read-write should be listed in both.
-  // |fast_check_in_client| and |quiet_failures_for_tests| are reserved for
-  // unit tests, don't use it.
-
+  // or Access() are invoked on a file which is not in the whitelist (EACCESS
+  // would be a typical value). |permissions| describes the whitelisted set
+  // of files the broker is is allowed to access. |fast_check_in_client|
+  // controls whether doomed requests are first filtered on the client side
+  // before being proxied. Apart from tests, this should always be true since
+  // our main clients are not always well-behaved. They may have third party
+  // libraries that don't know about sandboxing, and typically try to open all
+  // sorts of stuff they don't really need. It's important to reduce this load
+  // given that there is only one pipeline to the broker process, and it is
+  // not multi-threaded. |quiet_failures_for_tests| is reserved for unit tests,
+  // don't use it.
   BrokerProcess(
       int denied_errno,
       const std::vector<syscall_broker::BrokerFilePermission>& permissions,
@@ -52,6 +55,7 @@ class SANDBOX_EXPORT BrokerProcess {
       bool quiet_failures_for_tests = false);
 
   ~BrokerProcess();
+
   // Will initialize the broker process. There should be no threads at this
   // point, since we need to fork().
   // broker_process_init_callback will be called in the new broker process,
@@ -63,6 +67,7 @@ class SANDBOX_EXPORT BrokerProcess {
   // doesn't support execute permissions.
   // It's similar to the access() system call and will return -errno on errors.
   int Access(const char* pathname, int mode) const;
+
   // Can be used in place of open(). Will be async signal safe.
   // The implementation only supports certain white listed flags and will
   // return -EPERM on other flags.