From b5f29d5d2cfd2b17cda5543fec0bcbdd3fa5c372 Mon Sep 17 00:00:00 2001
From: peterbell10 <peterbell10@live.co.uk>
Date: Tue, 24 Jul 2018 22:30:05 +0100
Subject: Stop cFunctionRef constructor from disabling default copy
 constructor. (#4173)

* Stop cFunctionRef constructor from disabling default copy constructor.
+ cFunctionRef: Improve documentation
---
 src/FunctionRef.h | 37 +++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

(limited to 'src/FunctionRef.h')

diff --git a/src/FunctionRef.h b/src/FunctionRef.h
index 8215fd0db..753d540a7 100644
--- a/src/FunctionRef.h
+++ b/src/FunctionRef.h
@@ -6,17 +6,42 @@ template <class Signature>
 class cFunctionRef;
 
 /** A light-weight, type-erased reference to a function object.
-This is similar to a std::function but doesn't copy the function object
-which means that mutable function objects will be modified for the caller
-but would not be if using a std::function (See #3990 for implications of this).
-A cFunctionRef has no empty state but is non-owning and so is safe to call
-as long as the referred object is still alive. */
+
+### Usage
+
+`cFunctionRef` is used whenever you call a normal function with a lambda. e.g.
+one of the `cWorld::DoWith` functions,
+
+	m_World->DoWithChunkAt(BlockPos, [](cChunk & a_Chunk) -> bool
+		{
+			...
+		}
+	);
+
+It looks like you're calling it with a lambda but that would require
+`DoWithChunkAt` to be a template. The function is really being called with
+`cFunctionRef<bool(cChunk&)>` which is constructed from the lambda via a
+templated constructor. This gives you a generic pointer to the lambda which
+doesn't depend on the type of the function object it references.
+
+### Notes
+
+- This is similar to a `std::function` but doesn't copy the function object.
+This means that mutable function objects will be modified for the caller but
+would not be if using a `std::function` (See #3990 for implications of this).
+
+- A `cFunctionRef` has no empty state but is non-owning and so is safe to call as
+long as the referred object is still alive. */
 template <class Ret, class... Args>
 class cFunctionRef<Ret(Args...)>
 {
 public:
 	/** Construct from a function object. */
-	template <class FunctionObject>
+	template <class FunctionObject,
+		typename std::enable_if<  // Don't disable the default copy constructor
+			!std::is_same<typename std::decay<FunctionObject>::type, cFunctionRef>::value,
+		int>::type = 0
+	>
 	cFunctionRef(FunctionObject && a_FunctionObject)
 	{
 		// Store an opaque reference to the object.
-- 
cgit v1.2.3