Error message on invalid tag somewhat obtuse and doesn't point out the issue being the undefined tag

[luiz00martins]

This error happens even if there's no actual file being processed (i.e. all files are no module() call found; no initial doc comment).

The error happens when executing ldoc <path_to_folder>. LDoc works fine however when executing ldoc <path_to_specific_lua_file>.

Full error message:

template failed for scripts.lib.utils.random: ...apps/luarocks/current/rocks/share/lua/5.4/ldoc\tools.lua:221: invalid value (table) at index 1 in table for 'concat'
stack traceback:
        [C]: in function 'table.concat'
        ...apps/luarocks/current/rocks/share/lua/5.4/ldoc\tools.lua:221: in function 'ldoc.tools.join'
        (...tail calls...)
        [string "TMP"]:311: in function <[string "TMP"]:1>
        [C]: in function 'xpcall'
        ...pps/luarocks/current/rocks/share/lua/5.4/pl\template.lua:140: in function <...pps/luarocks/current/rocks/share/lua/5.4/pl\template.lua:133>
        (...tail calls...)
        .../apps/luarocks/current/rocks/share/lua/5.4/ldoc\html.lua:283: in local 'templatize'
        .../apps/luarocks/current/rocks/share/lua/5.4/ldoc\html.lua:375: in function 'ldoc.html.generate_output'
        ...rrent\rocks\lib\luarocks\rocks-5.4\ldoc\1.4.6-2\bin\ldoc:830: in main chunk
        [C]: in ?

I'm using windows 10, with lua 5.4.2, ldoc 1.4.6

Edit: Was able to replicate the same issue in Pop OS.

[luiz00martins]

I have tracked down the issue to comments with wrong tags (such as the @description found on this lua implementation for a RNG):

---
-- @description creates an instance of the rng
-- @return table an instance of the rng
--

The following error can also happen:

template failed for lib.utils.random: ...pps/luarocks/current/rocks/share/lua/5.4/ldoc\markup.lua:302: attempt to call a nil value (method 'gsub')
stack traceback:
        ...pps/luarocks/current/rocks/share/lua/5.4/ldoc\markup.lua:302: in function 'ldoc.markup.processor'
        (...tail calls...)
        [string "TMP"]:153: in function <[string "TMP"]:1>
        [C]: in function 'xpcall'
        ...pps/luarocks/current/rocks/share/lua/5.4/pl\template.lua:140: in function <...pps/luarocks/current/rocks/share/lua/5.4/pl\template.lua:133>
        (...tail calls...)
        .../apps/luarocks/current/rocks/share/lua/5.4/ldoc\html.lua:283: in local 'templatize'
        .../apps/luarocks/current/rocks/share/lua/5.4/ldoc\html.lua:375: in function 'ldoc.html.generate_output'
        ...rrent\rocks\lib\luarocks\rocks-5.4\ldoc\1.4.6-2\bin\ldoc:830: in main chunk
        [C]: in ?

After removing the wrong tag, the error is solved.

Should this have a better error message?

[alerque]

Can you post an MWE and the error with error you get with v1.5.0? The example you show seems to work fine more me (in that it gives a sensible error about what is wrong with the input) not the stack trace you are showing.

[luiz00martins]

Apparently I'm running 1.4.6 (It's the latest one available on luarocks).

I'll try it later on a manually installed copy of 1.5.0.

[alerque]

Ldoc v1.5.0 has been on LuaRocks since a few seconds of the tag being pushed to GitHub. What makes you say 1.4.6 is the latest?

[luiz00martins]

I guess I just had an old version. Doesn't matter though, I'm still having the issue on 1.5.0.

I'll try to produce a MWE

[luiz00martins]

Yeah, I'm not sure why you're not getting the error. This is enough for me to reproduce it:

---
-- @description get a clone of the current state
-- @return a table representing the full state, containing mti (number) and mt (table of numbers)
function getState()
	local r = {}
	r.mti = mti
	r.mt = {}
	for i=0,N-1 do
		r.mt[i] = mt[i]
	end
	return r
end

Which yields the error:

[REDACTED]\lib\utils\random.lua:1: contains no items
template failed for random: ...pps/luarocks/current/rocks/share/lua/5.4/ldoc\markup.lua:313: attempt to call a nil value (method 'gsub')
stack traceback:
        ...pps/luarocks/current/rocks/share/lua/5.4/ldoc\markup.lua:313: in function 'ldoc.markup.processor'
        (...tail calls...)
        [string "TMP"]:174: in function <[string "TMP"]:1>
        [C]: in function 'xpcall'
        ...pps/luarocks/current/rocks/share/lua/5.4/pl\template.lua:140: in function <...pps/luarocks/current/rocks/share/lua/5.4/pl\template.lua:133>
        (...tail calls...)
        .../apps/luarocks/current/rocks/share/lua/5.4/ldoc\html.lua:283: in local 'templatize'
        .../apps/luarocks/current/rocks/share/lua/5.4/ldoc\html.lua:320: in function 'ldoc.html.generate_output'
        ...rrent\rocks\lib\luarocks\rocks-5.4\ldoc\1.5.0-1\bin\ldoc:898: in main chunk
        [C]: in ?

---

Specs:

• Ldoc 1.5.0
• Windows 10 Home 19044.2846
• Lua 5.4.2

(You can ask for more info if you wish. I'm just not sure what info would help)

[alerque]

I am able to reproduce that error, but not with the original circumstances of "it throws an error when pointing to the directory but works if pointing directly to a single file". I get the error when calling just on the file too. Is that still the case for you?

[alerque]

Also, this error appears to be caused because you are using an undefined tag. Change -- @description get a ... to -- get a ... and it seems to work fine. Where did you get @description from?

[luiz00martins]

I am able to reproduce that error, but not with the original circumstances of "it throws an error when pointing to the directory but works if pointing directly to a single file". I get the error when calling just on the file too. Is that still the case for you?

Yep. I can't replicate that anymore. It also fails with just the file.

Also, this error appears to be caused because you are using an undefined tag. Change -- @description get a ... to -- get a ... and it seems to work fine. Where did you get @description from?

I already mentioned that it's caused by @description, and which repo it comes from, an RNG implementation. See comment #389 (comment).

My contention is not really that an error happens, but that it is obtuse and it doesn't point to why. It simply fails catastrophically.

I think it should still fail, with with a clean message, such as "Error in path/to/file.lua, line 116: invalid tag '@description' used", or something akin to that.

[alerque]

I missed that detail on trying to catch up the issue. I think it's clear now with an MWE and what needs fixing. This should be a relatively easy one to add a test with explicit error rather than falling through to a Lua error indexing undefined keys if anybody wants to tackle this.