Re: LDoc: False multiple returns

[TW <zupftom@...>]

Thanks, Stephen.


2015-12-23 0:17 GMT+01:00 Stephen Irons <stephen.irons@clear.net.nz>:
>
> The problem goes away if you include a description for the function, either on the same line as the luadoc comment marker (three dashes), or on subsequent lines.
>


That is absolutely right.


> This might be considered a bug with luadoc, but it is probably not important to fix: it would be poor form to have a function without a description.



To explain why I omitted the description - in the given case it
actually looks more like this:


    ---
    -- Returns the path of the current document.
    -- @function currentDocumentPath
    -- @treturn string
    --    Path of the current document.
    local function currentDocumentPath()
        -- some code ...
        return path
    end


I'd consider this somewhat overdocumented.  The function name already
says it all, and both the return value documentation and the function
description restate it in words.  To avoid duplication and make the
generated documentation nicer, I'd rather omit the general function
description rather than the return description.

Anyway, this is probably the wrong place to discuss this.  I spent
some time trying to understand where LDoc inserts the additional
return, but I wasn't successful (yet).


Thomas W.