Can Anybody Explain Why You Need To Return The Function in Line 4?

In programming especially Java we often wrap thing to obtain additional functionality when needed. The purpose of the debounce module it to apply a new debounce for the function that is passed.

To look at how this works we can break down the code into stages. Note this example is not using a module as it is easier to show in one script:-

local deb = false -- scope is outside the function
local function deb()

	if deb then return end	-- check and return out of code
	deb = true	
	
	-- code
	
	deb = false
end

The code above is the basic setup of a debounce. The down side is that this would require us to hard code each new deb variable. To resolve this we can wrap one function with this debounce variable which requiores a new function to be created. the call would be deb function -> passed function.

This can be show as:-

local function deb(func)
	local deb = false	 -- the scope of this variable only exists within the returned function so each function passed has its own variable that is not shared.
	
	-- wrap our passed function in a new function which only holds the debounce logic
	return function()
		if deb then return end
		deb  = true

		-- run our function passed in deb 
		func()
		
		deb = false
	end
end

This would work in some cases but we still rewuire and arguments that are passed when the function is ran ie

local newFunction = deb(function(txt) print(txt) end)
newFunction('hi') -- this would not print as we have not passed any arguments.

To resolve this we use .. for a Variable Number of Arguments which is as simepe as passing the arguments from our new function to our passed function.

local function deb(func)
	local deb = false	

	return function(...) -- all arguments 
		if deb then return end
		deb = true
		
		func(...) -- pass all arguments

		deb = false
	end
end

But what about a return value? In the wiki this code is designed to work for functions passed to events which do not require a return. This however can be added in.

local function deb(func)
	local deb = false	

	return function(...) 
		if deb then return end
		deb = true
		
		local res =  {func(...)} 
		
		-- we must set the debounce and not just return the functions result 
		deb = false
		return  unpack(res) -- unpack the table and pass back the arguments
	end
end

This example above will also handle passed arguments e.g

local function deb(func)
	local deb = false	

	return function(...) 
		if deb then return end
		deb = true
		
		local res =  {func(...)} 

		deb = false
		return  unpack(res) 
	end
end

local tmpF = deb(function(a) return a, 'b' end)

local a, b = tmpF('a')
print(a,b) -- prints a and b

Some points on module scripts A module script is used to share the same code in multiple places. It is very common to have a deounce used so putting it in a module is the logical solution.

A module must return one value in most cases they return a table which holds all of the functions available.

As showm above this code is not dependant on a moudle script it is simply used as a means not to dublicate code.

I hope this helps. please comment if you do not understand how / why this code works.