ldoc icon indicating copy to clipboard operation
ldoc copied to clipboard

Cannot use multiple @raise on a single Function

Open ktalebian opened this issue 6 years ago • 3 comments
trafficstars

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]: ?

ktalebian avatar Feb 28 '19 07:02 ktalebian

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.)

dnebauer avatar Dec 15 '19 14:12 dnebauer

Still can replicate this in the latest version.

luiz00martins avatar Mar 28 '23 13:03 luiz00martins

Looks like this is still around in v1.5.0 too. Anybody want to tackle it?

alerque avatar May 04 '23 22:05 alerque