Inferring return value documentation

[agladysh]

trafficstars

Would be cool if something like this would work:

--- Captures location in source code at given call stack level.
-- @see debug.getinfo
local capture_source_location = function(
    level -- @number[opt=1] call stack level
  )
  level = level or 1

  arguments("number", level)

  local info = debug_getinfo(level + 1, "Sl")
  if not info then
    --- requested call stack level is larger than
    -- number of functions currently in the call stack.
    return nil 
  end

  return --- A source code location
  {
    source = info.source;     -- @string exact source filename
    file = info.short_src;    -- @string short source filename
    line = info.currentline;  -- @number a line number in the source file
  }
end

Should yield something like this:

---

capture_source_location ([level=1])

Captures location in source code at given call stack level.

Parameters:

• level:number (default: 1): call stack level.

Returns:

Either:

• nil: requested call stack level is larger than number of functions currently in the call stack.

or

• A source code location table:
  • source:string: exact source filename,
  • file:string: short source filename,
  • line:number: a line number in the source file.

See also:

• debug.getinfo

---

As usual, exact wording can be improved.