Minor UI adjustments

config.ld

@@ -1,15 +1,20 @@
 dir = "ldoc_output"
-file = {".", exclude = {"spec"}}
+file = {".", exclude = {"spec", "mtt.lua", "doc_ui.lua"}}
 format = "markdown"
 project = "Documentation System Integration for Advtrains"
 title = "Manual for advtrains_doc_integration"
 readme = "README.md"
 
-custom_see_handler("^advtrains%.[%w%._]+$", function(name)
-	return name, "https://git.bananach.space/advtrains.git/tree/advtrains/api_doc.txt"
-end)
-custom_see_handler("^SimpleSoundSpec$", function()
-	return "SimpleSoundSpec", "https://api.minetest.net/sounds/#simplesoundspec"
-end)
+local function simple_see_handler(pattern, link)
+	custom_see_handler(pattern, function(name)
+		return name, link
+	end)
+end
+
+local MT_API = "https://api.minetest.net"
+
+simple_see_handler("^advtrains%.[%w%._]+$", "https://git.bananach.space/advtrains.git/tree/advtrains/api_doc.txt")
+simple_see_handler("^SimpleSoundSpec$", MT_API .. "/sounds/#simplesoundspec")
+simple_see_handler("^ItemStack$", MT_API .. "/class-reference/#itemstack")
 
 -- vim: ft=lua

doc_ui.lua

@@ -28,14 +28,6 @@ local function addlist(lst, tbl, title, fallback1, fallback2, mapf)
 	end
 end
 
-local function list_itemstring(x)
-	local item = ItemStack(x)
-	if item:is_empty() then
-		return S("Emptyness")
-	end
-	return string.format("%s: %d", item:get_short_description(), item:get_count())
-end
-
 local function blankline(st)
 	return table.insert(st, "")
 end
@@ -73,10 +65,10 @@ local function doc_render_wagon_information(prototype, pname)
 	end
 	table.insert(desctext, H.header(S("Basic Information")))
 	table.insert(desctext, S("Itemstring: @1", H.mono(prototype.name)))
-	addlist(desctext, prototype.drops, S("Drops:"), S("Drops nothing"), false, function(_, v) return list_itemstring(v) end)
+	addlist(desctext, prototype.drops, S("Drops:"), S("Drops nothing"), false, function(_, v) return H.describe_item(v) end)
 	addlist(desctext, prototype.drives_on, S("Drives on:"), nil, nil, H.mono)
-	addlist(desctext, prototype.coupler_types_front, S("Compatible front couplers:"), S2("Front coupler: @1", "Absent"), S2("Front coupler: @1", "Universal"), utils.get_coupler_name)
-	addlist(desctext, prototype.coupler_types_back, S("Compatible rear couplers:"), S2("Rear coupler: @1", "Absent"), S2("Rear coupler: @1", "Universal"), utils.get_couple_name)
+	addlist(desctext, prototype.coupler_types_front, S("Compatible front couplers:"), S2("Front coupler: @1", "Absent"), S2("Front coupler: @1", "Universal"), H.describe_coupler)
+	addlist(desctext, prototype.coupler_types_back, S("Compatible rear couplers:"), S2("Rear coupler: @1", "Absent"), S2("Rear coupler: @1", "Universal"), H.describe_coupler)
 	table.insert(desctext, S("Wagon span: @1", prototype.wagon_span and D.length(2*prototype.wagon_span) or S("Undefined")))
 	table.insert(desctext, S("Maximum speed: @1", prototype.max_speed and D.speed(prototype.max_speed) or S("Undefined")))
 	table.insert(desctext, S2("Motive power: @1", prototype.is_locomotive and "Present" or "Absent"))

hypertext.lua

@@ -3,6 +3,7 @@
 -- @alias H
 local H = {}
 local S = minetest.get_translator("advtrains_doc_integration")
+local utils = advtrains_doc_integration.utils
 
 --- Create a plain text hypertext element.
 -- @tparam string str The content of the element.
@@ -89,4 +90,30 @@ function H.describe_sound(action, soundspec)
 	return sounddesc
 end
 
+--- Describe a coupler type.
+-- @tparam string coupler The name of the coupler.
+-- @treturn string The hypertext element describing the coupler.
+function H.describe_coupler(coupler)
+	local name = utils.get_coupler_name(coupler)
+	if name then
+		return ("%s (%s)"):format(H.plain(name), H.mono(coupler))
+	else
+		return H.mono(coupler)
+	end
+end
+
+--- Describe an item.
+-- @tparam ItemStack item The item to describe
+-- @treturn string The hypertext element describing the item.
+function H.describe_item(item)
+	item = ItemStack(item)
+	if item:is_empty() then
+		return S("Emptyness")
+	end
+	local shortdesc = item:get_short_description()
+	local name = item:get_name()
+	local count = item:get_count()
+	return ("%s (%s): %d"):format(H.plain(shortdesc), H.mono(name), count)
+end
+
 return H

utils.lua

@@ -46,7 +46,7 @@ end
 -- @tparam string str The technical name of the coupler
 -- @treturn string The name of the coupler
 function utils.get_coupler_name(str)
-	return advtrains.coupler_types[str] or str
+	return advtrains.coupler_types[str]
 end
 
 --- Adjust the soundspec to table form.