summaryrefslogtreecommitdiff
path: root/absl/memory
diff options
context:
space:
mode:
authorGravatar Abseil Team <absl-team@google.com>2018-10-04 08:55:32 -0700
committerGravatar Alex Strelnikov <strel@google.com>2018-10-05 10:53:08 -0400
commite821380d69a549dc64900693942789d21aa4df5e (patch)
tree4969f84d2e677dfe645acfecc91d6c05e9c281a0 /absl/memory
parentf21d187b80e3b7f08fb279775ea9c8b48c636030 (diff)
Export of internal Abseil changes.
-- e09635c907d471ab46e14fb8091988c92cb4e78e by Abseil Team <absl-team@google.com>: Fix syntax error in documentation '}' -> ')' PiperOrigin-RevId: 215744854 -- a9e2d036850748137355f4a07083f1052d5c3766 by Abseil Team <absl-team@google.com>: WrapUnique's comment about avoiding explicit template specification doesn't make clear what alternative there is when this hurts readability. Add a comment about the approved alternative. PiperOrigin-RevId: 215634917 -- 596b8ff41ff70b27bff3a2369038c0fe7d13ae85 by Greg Falcon <gfalcon@google.com>: Allow for a small amount of slop in timeout tests, as not all OSs we support give us the perfect timing behavior we're testing for here. PiperOrigin-RevId: 215615172 GitOrigin-RevId: e09635c907d471ab46e14fb8091988c92cb4e78e Change-Id: I30721294bac86510a49bb7f405149fc74c532abb
Diffstat (limited to 'absl/memory')
-rw-r--r--absl/memory/memory.h24
1 files changed, 19 insertions, 5 deletions
diff --git a/absl/memory/memory.h b/absl/memory/memory.h
index a80aab0a..1eaec0f4 100644
--- a/absl/memory/memory.h
+++ b/absl/memory/memory.h
@@ -39,16 +39,30 @@ namespace absl {
// Function Template: WrapUnique()
// -----------------------------------------------------------------------------
//
-// Adopts ownership from a raw pointer and transfers it to the returned
-// `std::unique_ptr`, whose type is deduced. DO NOT specify the template type T
-// when calling WrapUnique.
+// Adopts ownership from a raw pointer and transfers it to the returned
+// `std::unique_ptr`, whose type is deduced. Because of this deduction, *do not*
+// specify the template type `T` when calling `WrapUnique`.
//
// Example:
// X* NewX(int, int);
// auto x = WrapUnique(NewX(1, 2)); // 'x' is std::unique_ptr<X>.
//
-// `absl::WrapUnique` is useful for capturing the output of a raw pointer
-// factory. However, prefer 'absl::make_unique<T>(args...) over
+// The purpose of WrapUnique is to automatically deduce the pointer type. If you
+// wish to make the type explicit, for readability reasons or because you prefer
+// to use a base-class pointer rather than a derived one, just use
+// `std::unique_ptr` directly.
+//
+// Example:
+// X* Factory(int, int);
+// auto x = std::unique_ptr<X>(Factory(1, 2));
+// - or -
+// std::unique_ptr<X> x(Factory(1, 2));
+//
+// This has the added advantage of working whether Factory returns a raw
+// pointer or a `std::unique_ptr`.
+//
+// While `absl::WrapUnique` is useful for capturing the output of a raw
+// pointer factory, prefer 'absl::make_unique<T>(args...)' over
// 'absl::WrapUnique(new T(args...))'.
//
// auto x = WrapUnique(new X(1, 2)); // works, but nonideal.