Document base::Bind*() and base::Callback*() in the headers.

Add basic documentation in the headers, so some of the invariants and
basic usage are more obvious without having to refer to a separate
Markdown document.

Change-Id: Ic14350c8745ba95c05f62be17760fb02c6f7bfef
Reviewed-on: https://chromium-review.googlesource.com/924744Reviewed-by: Avi Drissman <avi@chromium.org>
Reviewed-by: Taiju Tsuiki <tzik@chromium.org>
Commit-Queue: Daniel Cheng <dcheng@chromium.org>
Cr-Commit-Position: refs/heads/master@{#537688}

base/bind.h

@@ -13,8 +13,32 @@
 // Usage documentation
 // -----------------------------------------------------------------------------
 //
-// See //docs/callback.md for documentation.
+// Overview:
+// base::BindOnce() and base::BindRepeating() are helpers for creating
+// base::OnceCallback and base::RepeatingCallback objects respectively.
 //
+// For a runnable object of n-arity, the base::Bind*() family allows partial
+// application of the first m arguments. The remaining n - m arguments must be
+// passed when invoking the callback with Run().
+//
+//   // The first argument is bound at callback creation; the remaining
+//   // two must be passed when calling Run() on the callback object.
+//   base::OnceCallback<void(int, long)> cb = base::BindOnce(
+//       [](short x, int y, long z) { return x * y * z; }, 42);
+//
+// When binding to a method, the receiver object must also be specified at
+// callback creation time. When Run() is invoked, the method will be invoked on
+// the specified receiver object.
+//
+//   class C : public base::RefCounted<C> { void F(); };
+//   auto instance = base::MakeRefCounted<C>();
+//   auto cb = base::BindOnce(&C::F, instance);
+//   cb.Run();  // Identical to instance->F()
+//
+// base::Bind is currently a type alias for base::BindRepeating(). In the
+// future, we expect to flip this to default to base::BindOnce().
+//
+// See //docs/callback.md for the full documentation.
 //
 // -----------------------------------------------------------------------------
 // Implementation notes

base/callback.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.
+//
+// NOTE: Header files that do not require the full definition of Callback or
+// Closure should #include "base/callback_forward.h" instead of this file.
 
 #ifndef BASE_CALLBACK_H_
 #define BASE_CALLBACK_H_
@@ -8,14 +11,41 @@
 #include "base/callback_forward.h"
 #include "base/callback_internal.h"
 
-// NOTE: Header files that do not require the full definition of Callback or
-// Closure should #include "base/callback_forward.h" instead of this file.
-
 // -----------------------------------------------------------------------------
 // Usage documentation
 // -----------------------------------------------------------------------------
 //
-// See //docs/callback.md for documentation.
+// Overview:
+// A callback is similar in concept to a function pointer: it wraps a runnable
+// object such as a function, method, lambda, or even another callback, allowing
+// the runnable object to be invoked later via the callback object.
+//
+// Unlike function pointers, callbacks are created with base::BindOnce() or
+// base::BindRepeating() and support partial function application.
+//
+// A base::OnceCallback may be Run() at most once; a base::RepeatingCallback may
+// be Run() any number of times. |is_null()| is guaranteed to return true for a
+// moved-from callback.
+//
+//   // The lambda takes two arguments, but the first argument |x| is bound at
+//   // callback creation.
+//   base::OnceCallback<int(int)> cb = base::BindOnce([] (int x, int y) {
+//     return x + y;
+//   }, 1);
+//   // Run() only needs the remaining unbound argument |y|.
+//   printf("1 + 2 = %d\n", std::move(cb).Run(2));  // Prints 3
+//   printf("cb is null? %s\n", cb ? "true" : "false");  // Prints true
+//   std::move(cb).Run(2);  // Crashes since |cb| has already run.
+//
+// Callbacks also support cancellation. A common use is binding the receiver
+// object as a WeakPtr<T>. If that weak pointer is invalidated, calling Run()
+// will be a no-op. Note that |is_cancelled()| and |is_null()| are distinct:
+// simply cancelling a callback will not also make it null.
+//
+// base::Callback is currently a type alias for base::RepeatingCallback. In the
+// future, we expect to flip this to default to base::OnceCallback.
+//
+// See //docs/callback.md for the full documentation.
 
 namespace base {