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

Question

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

luiz00martins opened this issue a year ago · 10 comments

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.

Answer 1 · 2023-03-28T13:56:11.000Z

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?

Answer 2 · 2023-05-04T22:39:00.000Z

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.

Answer 3 · 2023-05-05T13:15:44.000Z

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.

Answer 4 · 2023-05-05T22:13:46.000Z

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?

Answer 5 · 2023-05-06T00:02:41.000Z

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

Answer 6 · 2023-05-06T00:11:02.000Z

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)

Answer 7 · 2023-05-06T14:50:17.000Z

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?

Answer 8 · 2023-05-06T14:54:54.000Z

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?

Answer 9 · 2023-05-07T07:34:58.000Z

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.

Answer 10 · 2023-05-07T07:46:50.000Z

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.