Error message on invalid tag somewhat obtuse and doesn't point out the issue being the undefined tag about ldoc HOT 10 OPEN

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?

from ldoc.

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.

from ldoc.

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.

from ldoc.

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?

from ldoc.

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

from ldoc.

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)

from ldoc.

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?

from ldoc.

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?

from ldoc.

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.

from ldoc.

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.

from ldoc.