Re: LDoc: False multiple returns

[steve donovan <steve.j.donovan@...>]

OK, this does feel like an interesting corner case - you have an
_empty_ function description, which I reckon should be valid and not
cause any weirdness.

On Wed, Dec 23, 2015 at 9:58 AM, TW <zupftom@googlemail.com> wrote:
> 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.
>