Function which behave depending on parameter type: How to document ?

[jjvbsag]

Following example

------------------------------------------------------------
-- get element from object
-- @param[type=number] tag index of object 1...n
-- @param[type=string] tag name of object to get
-- @return obj,idx (obj,number) object and index (2..)
--
function xmlobj:element(tag)

LDoc generates warnings in output

.../cxml.lua:51: xmlobj:element: extra param with no formal argument: 'tag'

And the document output is

xmlobj:element (tag, tag)
    get element from object
    Parameters:

        tag (string) name of object to get
        tag (string) name of object to get

    Returns:

        obj,idx (obj,number) object and index (2..) 

Can you give me an advice, how to correctly use LDoc for this case?

[Elv13]

Correct is not defined, but you can do

@tparam number|string tag Either the object index or a tag object. 

[jjvbsag]

I'm not happy :cry:

---

Have a look at treturn : I can do

-- @treturn[1] number interval in seconds
-- @treturn[2] string timepoint

and I'll get

Returns: (number) interval in seconds Or (string) timepoint

:+1: :100: :fireworks: :heart:

---

Now, when I try the same with tparam :

-- @tparam[1] number time interval in seconds
-- @tparam[2] string time timepoint

I'll get

Every(time, time) Parameters:

• time: (string) timepoint
• time: (string) timepoint

So

• :-1: ldoc does not recognize [1] and [2] for tparam. (But also gives no warning nor error)
• :+1: ldoc does show the parameter twice in the list
• :-1: ldoc does not keep track of different types or comments

What I'd expected, would be

Every(time) Parameters:

• time: (number) interval in seconds Or
• time: (string) timepoint

:sos: Can you give me a pointer, how to implement the same as in treturn also in tparam? :ambulance: