Submission for C++ Readability

device/bluetooth/bluetooth_adapter_chromeos.h

 // Copyright 2013 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 DEVICE_BLUETOOTH_BLUETOOTH_ADAPTER_CHROMEOS_H_
 #define DEVICE_BLUETOOTH_BLUETOOTH_ADAPTER_CHROMEOS_H_
 
 #include <map>
 #include <queue>
 #include <string>
@@ skipping 28 matching lines @@
 class BluetoothAdapterProfileChromeOS;
 class BluetoothDeviceChromeOS;
 class BluetoothPairingChromeOS;
 class BluetoothRemoteGattCharacteristicChromeOS;
 class BluetoothRemoteGattDescriptorChromeOS;
 class BluetoothRemoteGattServiceChromeOS;
 
 // The BluetoothAdapterChromeOS class implements BluetoothAdapter for the
 // Chrome OS platform.
 //
+// All methods are called from the dbus origin / UI thread and are generally
+// not assumed to be thread-safe.
+//
+// This class interacts with sockets using the BluetoothSocketThread to ensure
+// single-threaded calls, and posts tasks to the UI thread.
+//
 // Methods tolerate a shutdown scenario where BluetoothAdapterChromeOS::Shutdown
 // causes IsPresent to return false just before the dbus system is shutdown but
 // while references to the BluetoothAdapterChromeOS object still exists.
 //
 // When adding methods to this class verify shutdown behavior in
 // BluetoothChromeOSTest, Shutdown.
 class DEVICE_BLUETOOTH_EXPORT BluetoothAdapterChromeOS
     : public device::BluetoothAdapter,
       public chromeos::BluetoothAdapterClient::Observer,
       public chromeos::BluetoothDeviceClient::Observer,
@@ skipping 43 matching lines @@
   void RegisterAdvertisement(
       scoped_ptr<device::BluetoothAdvertisement::Data> advertisement_data,
       const CreateAdvertisementCallback& callback,
       const CreateAdvertisementErrorCallback& error_callback) override;
 
   // Locates the device object by object path (the devices map and
   // BluetoothDevice methods are by address).
   BluetoothDeviceChromeOS* GetDeviceWithPath(
       const dbus::ObjectPath& object_path);
 
-  // Announce to observers a change in device state that is not reflected by
-  // its D-Bus properties.
+  // Announces to observers a change in device state that is not reflected by
+  // its D-Bus properties. |device| is owned by the caller and cannot be NULL.
   void NotifyDeviceChanged(BluetoothDeviceChromeOS* device);
 
   // The following methods are used to send various GATT observer events to
   // observers.
   void NotifyGattServiceAdded(BluetoothRemoteGattServiceChromeOS* service);
   void NotifyGattServiceRemoved(BluetoothRemoteGattServiceChromeOS* service);
   void NotifyGattServiceChanged(BluetoothRemoteGattServiceChromeOS* service);
   void NotifyGattDiscoveryComplete(BluetoothRemoteGattServiceChromeOS* service);
   void NotifyGattCharacteristicAdded(
       BluetoothRemoteGattCharacteristicChromeOS* characteristic);
@@ skipping 253 matching lines @@
   // Note: This should remain the last member so it'll be destroyed and
   // invalidate its weak pointers before any other members are destroyed.
   base::WeakPtrFactory<BluetoothAdapterChromeOS> weak_ptr_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(BluetoothAdapterChromeOS);
 };
 
 }  // namespace chromeos
 
 #endif  // DEVICE_BLUETOOTH_BLUETOOTH_ADAPTER_CHROMEOS_H_