Document weak pointer factory constructor requirement.

base/memory/weak_ptr.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.
 
 // Weak pointers are pointers to an object that do not affect its lifetime,
 // and which may be invalidated (i.e. reset to NULL) by the object, or its
 // owner, at any time, most commonly when the object is about to be deleted.
 
 // Weak pointers are useful when an object needs to be accessed safely by one
 // or more objects other than its owner, and those callers can cope with the
 // object vanishing and e.g. tasks posted to it being silently dropped.
 // Reference-counting such an object would complicate the ownership graph and
 // make it harder to reason about the object's lifetime.
 
 // EXAMPLE:
 //
 //  class Controller {
 //   public:
+//    Controller() : weak_factory_(this) {}

[Nico, 2015/09/11 18:41:39]

It's not always `this`, is it? It's just the pointer the weak pointer handed out
by the factor points to, right? It could also be a pointer to e.g. a field of
this.

[scheib, 2015/09/11 19:40:29]

True, but in this example the factory vends Controller pointers.

 //    void SpawnWorker() { Worker::StartNew(weak_factory_.GetWeakPtr()); }
 //    void WorkComplete(const Result& result) { ... }
 //   private:
 //    // Member variables should appear before the WeakPtrFactory, to ensure
 //    // that any WeakPtrs to Controller are invalidated before its members
 //    // variable's destructors are executed, rendering them invalid.
 //    WeakPtrFactory<Controller> weak_factory_;
 //  };
 //
 //  class Worker {
@@ skipping 301 matching lines @@
 //   base::WeakPtr<Derived> ptr = derived.AsWeakPtr();  // Fails.
 
 template <typename Derived>
 WeakPtr<Derived> AsWeakPtr(Derived* t) {
   return internal::SupportsWeakPtrBase::StaticAsWeakPtr<Derived>(t);
 }
 
 }  // namespace base
 
 #endif  // BASE_MEMORY_WEAK_PTR_H_