Improve CloudPolicyClient doc.

components/policy/core/common/cloud/cloud_policy_client.h

 // Copyright (c) 2012 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 COMPONENTS_POLICY_CORE_COMMON_CLOUD_CLOUD_POLICY_CLIENT_H_
 #define COMPONENTS_POLICY_CORE_COMMON_CLOUD_CLOUD_POLICY_CLIENT_H_
 
 #include <stdint.h>
 
 #include <map>
@@ skipping 62 matching lines @@
 
     // Called when a request for device robot OAuth2 authorization tokens
     // returns successfully. Only occurs during enrollment. Optional
     // (default implementation is a noop).
     virtual void OnRobotAuthCodesFetched(CloudPolicyClient* client);
 
     // Indicates there's been an error in a previously-issued request.
     virtual void OnClientError(CloudPolicyClient* client) = 0;
   };
 
-  // |service| and |signing_service| are weak pointers and it's the caller's
-  // responsibility to keep them valid for the lifetime of CloudPolicyClient.
-  // |verification_key_hash| contains an identifier telling the DMServer which
-  // verification key to use. The |signing_service| is used to sign sensitive
-  // requests.
+  // |machine_id| and |machine_model| must only be provided for device
+  // policy. (Pass empty strings for user policy to prevent leaking machine
+  // details.) |service| and |signing_service| are weak pointers and it's the

[Mattias Nissler (ping if slow), 2016/09/27 13:48:45]

nit: This suggests that bad the code will not work if machine_id or
machine_model are passed for user policy, which is not true. Maybe soften to
something like this:

If non-empty, |machine_id| and |machine_model| are passed to the server
verbatimly. Note that these reveal machine identity to the server, so should
only be used where this is appropriate (i.e. device policy, but not user
policy).

+  // caller's responsibility to keep them valid for the lifetime of
+  // CloudPolicyClient.  |verification_key_hash| contains an identifier telling
+  // the DMServer which verification key to use. The |signing_service| is used
+  // to sign sensitive requests.
   CloudPolicyClient(
       const std::string& machine_id,
       const std::string& machine_model,
       const std::string& verification_key_hash,
       DeviceManagementService* service,
       scoped_refptr<net::URLRequestContextGetter> request_context,
       SigningService* signing_service);
   virtual ~CloudPolicyClient();
 
   // Sets the DMToken, thereby establishing a registration with the server. A
@@ skipping 319 matching lines @@
 
   // Used to create tasks which run delayed on the UI thread.
   base::WeakPtrFactory<CloudPolicyClient> weak_ptr_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(CloudPolicyClient);
 };
 
 }  // namespace policy
 
 #endif  // COMPONENTS_POLICY_CORE_COMMON_CLOUD_CLOUD_POLICY_CLIENT_H_