stairs: Add stairs.register_stair_type() to reduce duplicated code.

[orbea]

This is less than trivial cleanup, but should have no change in behavior and should be easy to update existing code whenever maintainers have time.

The problem is that mods/stairs/init.lua contains three large functions with largely duplicated code, stairs.register_stair(), stairs.register_stair_inner() and stairs.register_stair_outer() for creating regular, inner and outer corner stairs respectively. This is very hard to read while spotting the relatively minor differences between functions.

This adds a new function, stairs.register_stair_type() which combines all three functions with a single new argument, stairtype. It can be set as "inner" for inner corner stairs, "outer" for outer corner stairs and nil for regular stairs.

I also updated the existing uses in mods/stairs/init.lua, mods/farming/nodes.lua, updated the docs and added deprecation warnings for the old functions.

Please let me know if there is anything I missed.

[orbea]

I believe this is a small step that helps issue #2403.

With fewer redundant functions in the stairs mod it will be potentially easier to move code around.

[SmallJoker]

There's much redundant parts in the code - good to see some cleanups.
However, deprecating functions is not needed and the old ones should be kept for short-hand access for certain stair types.
register_stair_type would be a perfect name for registering more kinds of stairs. This caused some brainstorming for a more generic and extensible API, so here's the outcome of my thinking (ideas?)

Much code

-- Table containing templates to register a stair type
local mod_stair_types = {
	-- sample entry
	inner = {
		recipe = {
			-- replace 1 with supplied recipeitem
			{"", 1, ""},
			{1, "",  1},
			{1,  1,  1},
		},
		-- either: mesh = "demo.b3d"
		-- or: node_box:
		node_box = {
			-- etc
		}
	},
	-- etc
}

local function register_stair(type, modname, nodename, description, def)
	local typedef = mod_stair_types[type]
	assert(typedef, "Unknown type")

	-- Register node and crafting based on the mod_stair_types entry
	-- modname:stair_type_nodename
	minetest.register_node(("%s:stair_%s_%s"):format(
			modname, type, nodename), {
		description = description,
		sounds = def.sounds,
		-- etc
	})
end

function stairs.register_stair(...)
	local def = {...}
	if #def >= 5 then
		-- Old notation required at least 5 args
		return legacy_stair_registration(...)
	end
	assert(#def == 3, "Invalid usage. 3 args expected")

	local modname  = def[1]
	local nodename = def[2]
	def = def[3] -- recycle name

	for type, description in ipairs(def.types)
		register_stair(type, modname, nodename, description, def)
	end
end

-- register new kind of stair
function stairs.register_stair_type(typename, typedef)
	assert(not mod_stair_types[typename], "Type already registered")
	-- TODO: santity checks, defaults
	mod_stair_types[typename] = typedef
end


-- Examples for usage in mods

stairs.register_stair_type("slope", {
	recipe = {
		-- etc
	},
	mesh = "example.b3d",
	-- etc
})

stairs.register_stair("mymod", "barking_wood", {
	types = {
		inner = S("Inner Barking Wood Stair"),
		outer = S("Outer Barking Wood Stair"),
		slope = S("Barking Wood Slope"), -- is translation-friendly
	},
	recipeitem = "mymod:barking_wood_plank",
	sound = -- etc
	groups = -- etc
})

[orbea]

However, deprecating functions is not needed and the old ones should be kept for short-hand access for certain stair types.

Thanks, you gave me some good ideas how to improve this, but I'm not sure I agree with this part.

The problem I saw was both that there is a lot of redundant code and also that there are multiple redundant / similar functions. I'm not sure how that is an improvement to have 4 redundant functions instead of 3? This will just lead to greater confusion on which function to use for inexperienced modders and greater technical debt making sure they all stay in sync.

I think this classic xkcd shows the problem. :)

https://xkcd.com/927/