Discourage base::ResetAndReturn().

See discussion at
https://groups.google.com/a/chromium.org/forum/#!topic/chromium-dev/PJOXupl9ztA

Bug: 841899
Change-Id: I58158270f304c5e6d50a85d47e1d3f599b5870d5
Reviewed-on: https://chromium-review.googlesource.com/1053831
Commit-Queue: Bence Béky <bnc@chromium.org>
Reviewed-by: Nico Weber <thakis@chromium.org>
Cr-Commit-Position: refs/heads/master@{#557665}

base/callback_helpers.h

@@ -6,10 +6,6 @@
 // are implemented using templates, with a class per callback signature, adding
 // methods to Callback<> itself is unattractive (lots of extra code gets
 // generated).  Instead, consider adding methods here.
-//
-// ResetAndReturn(&cb) is like cb.Reset() but allows executing a callback (via a
-// move or copy) after the original callback is Reset().  This can be handy if
-// Run() reads/writes the variable holding the Callback.
 
 #ifndef BASE_CALLBACK_HELPERS_H_
 #define BASE_CALLBACK_HELPERS_H_
@@ -25,6 +21,7 @@
 
 namespace base {
 
+// Prefer std::move() over ResetAndReturn().
 template <typename CallbackType>
 CallbackType ResetAndReturn(CallbackType* cb) {
   CallbackType ret(std::move(*cb));

docs/callback.md

@@ -155,12 +155,13 @@ void DoSomething(const base::RepeatingCallback<double(double)>& callback) {
 
 If running a callback could result in its own destruction (e.g., if the callback
 recipient deletes the object the callback is a member of), the callback should
-be moved before it can be safely invoked. The `base::ResetAndReturn` method
-provides this functionality.
+be moved before it can be safely invoked. (Note that this is only an issue for
+RepeatingCallbacks, because a OnceCallback always has to be moved for
+execution.)
 
 ```cpp
 void Foo::RunCallback() {
-  base::ResetAndReturn(&foo_deleter_callback_).Run();
+  std::move(&foo_deleter_callback_).Run();
 }
 ```