Tidy base::Scoped*Observation classes.

This addresses nits from https://crrev.com/c/2518028, and generally
tides up ScopedObservation and ScopedMultiSourceObservation.

Bug: 1145565
Change-Id: I6aa515b25eede775b17a21b34f688e3daf8410a7
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2533899Reviewed-by: Gabriel Charette <gab@chromium.org>
Commit-Queue: Sigurður Ásgeirsson <siggi@chromium.org>
Cr-Commit-Position: refs/heads/master@{#826833}

base/scoped_multi_source_observation.h

@@ -15,33 +15,36 @@
 
 namespace base {
 
-// ScopedMultiSourceObservation is used to keep track of the set of sources an
-// object has attached itself to as an observer.
+// ScopedMultiSourceObservation is used to keep track of plural observation,
+// e.g. where an observer observes more than a single source.
 //
-// For objects that observe only a single source, use base::ScopedObservation
-// rather than this class. This class and base::ScopedObservation replace
-// ScopedObserver.
+// Use base::ScopedObservation for objects that observe only a single source.
+// This class and base::ScopedObservation replace ScopedObserver.
 //
-// When ScopedMultiSourceObservation is destroyed it removes the object as an
+// When ScopedMultiSourceObservation is destroyed, it removes the object as an
 // observer from all sources it has been added to.
 // Basic example (as a member variable):
 //
 //   class MyFooObserver : public FooObserver {
 //     ...
 //    private:
-//     ScopedMultiSourceObservation<Foo, FooObserver> observed_foo_{this};
+//     ScopedMultiSourceObservation<Foo, FooObserver> foo_observations_{this};
 //   };
 //
+//   MyFooObserver::OnFooCreated(Foo* foo) {
+//     foo_observations_.AddObservation(foo);
+//   }
+//
 // For cases with methods not named AddObserver/RemoveObserver:
 //
 //   class MyFooStateObserver : public FooStateObserver {
 //     ...
 //    private:
-//     ScopedMultiSourceObservation<Foo,
-//                    FooStateObserver,
-//                    &Foo::AddStateObserver,
-//                    &Foo::RemoveStateObserver>
-//       observed_foo_{this};
+//      ScopedMultiSourceObservation<Foo,
+//                                  FooStateObserver,
+//                                  &Foo::AddStateObserver,
+//                                  &Foo::RemoveStateObserver>
+//          foo_observations_{this};
 //   };
 template <class Source,
           class Observer,
@@ -70,22 +73,27 @@ class ScopedMultiSourceObservation {
     (source->*RemoveObsFn)(observer_);
   }
 
+  // Remove the object passed to the constructor as an observer from all sources
+  // it's observing.
   void RemoveAllObservations() {
     for (Source* source : sources_)
       (source->*RemoveObsFn)(observer_);
     sources_.clear();
   }
 
+  // Returns true if any source is being observed.
+  bool IsObservingAnySource() const { return !sources_.empty(); }
+
+  // Returns true if |source| is being observed.
   bool IsObservingSource(Source* source) const {
     return base::Contains(sources_, source);
   }
 
-  bool IsObservingAnySource() const { return !sources_.empty(); }
-
+  // Returns the number of sources being observed.
   size_t GetSourcesCount() const { return sources_.size(); }
 
  private:
-  Observer* observer_;
+  Observer* const observer_;
 
   std::vector<Source*> sources_;
 };

base/scoped_observation.h

@@ -11,7 +11,13 @@
 
 namespace base {
 
-// ScopedObservation is used to keep track of a single observation.
+// ScopedObservation is used to keep track of singular observation, e.g.
+// where an observer observes a single source only.
+//
+// Use base::ScopedMultiSourceObservation for objects that observe multiple
+// sources. This class and base::ScopedMultiSourceObservation replace
+// ScopedObserver.
+//
 // When ScopedObservation is destroyed, it removes the registered observation,
 // if any. Basic example (as a member variable):
 //
@@ -21,19 +27,21 @@ namespace base {
 //     ScopedObservation<Foo, FooObserver> foo_observation_{this};
 //   };
 //
+//   MyFooObserver::MyFooObserver(Foo* foo) {
+//     foo_observation_.Observe(foo);
+//   }
+//
 // For cases with methods not named AddObserver/RemoveObserver:
 //
 //   class MyFooStateObserver : public FooStateObserver {
 //     ...
 //    private:
 //     ScopedObservation<Foo,
-//                    FooStateObserver,
-//                    &Foo::AddStateObserver,
-//                    &Foo::RemoveStateObserver>
-//       observed_foo_{this};
+//                       FooStateObserver,
+//                       &Foo::AddStateObserver,
+//                       &Foo::RemoveStateObserver>
+//       foo_observation_{this};
 //   };
-//
-// See also base::ScopedObserver to manage observations from multiple sources.
 template <class Source,
           class Observer,
           void (Source::*AddObsFn)(Observer*) = &Source::AddObserver,