ldoc
ldoc copied to clipboard
Cannot use multiple @raise on a single Function
If you set multiple @raise such as
--- Some Function
-- @return something
-- @raise error 1 that can be thrown
-- @raise error 2 that can be thrown
function _M.someFunction()
...
end
You get
template failed for client: .../lua_modules/share/lua/5.1/ldoc/markup.lua:302: attempt to call method 'gsub' (a nil value)
stack traceback:
.../lua_modules/share/lua/5.1/ldoc/markup.lua:302: in function <.../lua_modules/share/lua/5.1/ldoc/markup.lua:299>
(tail call): ?
[string "TMP"]:580: in function <[string "TMP"]:1>
[C]: in function 'xpcall'
.../lua_modules/share/lua/5.1/pl/template.lua:138: in function <.../lua_modules/share/lua/5.1/pl/template.lua:131>
(tail call): ?
.../lua_modules/share/lua/5.1/ldoc/html.lua:283: in function 'templatize'
.../lua_modules/share/lua/5.1/ldoc/html.lua:375: in function 'generate_output'
...modules/lib/luarocks/rocks-5.1/ldoc/1.4.6-2/bin/ldoc:830: in main chunk
[C]: ?
For those new to this tool, one workaround for multiple raises (and, I presume, multiples of other singleton tags) is to use a single @raise tag but use markdown formatting to clearly show the separate errors.
For example, format the original example above as a list by altering it to:
--- Some Function
-- @return something
-- @raise * error 1 that can be thrown
-- * error 2 that can be thrown
And make sure to process the documentation as markdown by using the -f command line option to specify a markdown processor. For example:
ldoc -f markdown ./
Other possible markdown processors are plain and discount. (See the ldoc documentation for more details.)
Still can replicate this in the latest version.
Looks like this is still around in v1.5.0 too. Anybody want to tackle it?