Improve DeviceSettingsService documentation

chrome/browser/chromeos/settings/device_settings_service.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 CHROME_BROWSER_CHROMEOS_SETTINGS_DEVICE_SETTINGS_SERVICE_H_
 #define CHROME_BROWSER_CHROMEOS_SETTINGS_DEVICE_SETTINGS_SERVICE_H_
 
 #include <deque>
 #include <memory>
 #include <string>
@@ skipping 93 matching lines @@
                          scoped_refptr<ownership::OwnerKeyUtil> owner_key_util);
 
   // Prevents the service from making further calls to session_manager_client
   // and stops any pending operations.
   void UnsetSessionManager();
 
   // Must only be used with a |device_mode| that has been read and verified by
   // the InstallAttributes class.
   void SetDeviceMode(policy::DeviceMode device_mode);
 
-  const enterprise_management::PolicyData* policy_data() {
+  const enterprise_management::PolicyData* policy_data() const {
     return policy_data_.get();
   }
 
   // Returns the currently active device settings. Returns nullptr if the device
   // settings have not been retrieved from session_manager yet.
   const enterprise_management::ChromeDeviceSettingsProto*
       device_settings() const {
     return device_settings_.get();
   }
 
   // Returns the currently used owner key.
   scoped_refptr<ownership::PublicKey> GetPublicKey();
 
-  // Returns the status generated by the last operation.
-  Status status() { return store_status_; }
+  // Returns the status generated by the *last operation*.

[emaxx, 2017/06/01 20:13:31]

nit: What about also renaming this method so that this peculiarity becomes
obvious? E.g. last_operation_status.

[Thiemo Nagel, 2017/06/02 11:25:39]

I might do that in a follow-up CL.  Ideally, the observers should pass the
status so that the status() method can be removed completely.  I haven't looked
through the code enough to understand whether that would be feasible, though.

+  // WARNING: It is not correct to take this method as an indication of whether
+  // DeviceSettingsService contains valid device settings. In order to answer
+  // that question, simply check whether device_settings() is different from
+  // nullptr.
+  Status status() const { return store_status_; }
 
   // Triggers an attempt to pull the public half of the owner key from disk and
   // load the device settings.
   void Load();
 
   // Synchronously pulls the public key and loads the device settings.
   void LoadImmediately();
 
   // Stores a policy blob to session_manager. The result of the operation is
   // reported through |callback|. If successful, the updated device settings are
@@ skipping 131 matching lines @@
   ScopedTestDeviceSettingsService();
   ~ScopedTestDeviceSettingsService();
 
  private:
   DISALLOW_COPY_AND_ASSIGN(ScopedTestDeviceSettingsService);
 };
 
 }  // namespace chromeos
 
 #endif  // CHROME_BROWSER_CHROMEOS_SETTINGS_DEVICE_SETTINGS_SERVICE_H_