Re: [ANN]otate

[oliver <oliver.schoenborn@...>]

  [*]: Ahh, new idea: Unit testing using examples in the docstring ...

You're probably being sarcastic since you are using the term "docstring", but if not, you might get some ideas from python's doctest module [1], which is rather mature.

[1] http://en.wikipedia.org/wiki/Doctest 

On Thu, Apr 25, 2013 at 8:43 AM, Philipp Janda <siffiejoe@gmx.net> wrote:

Am 25.04.2013 08:29 schröbte Geoff Leyland:

Hi Phillip,

Hi!

On 25/04/2013, at 10:02 AM, Philipp Janda <siffiejoe@gmx.net> wrote:

Hello fellow Lua users!

Do you like Python's docstrings or their Lua equivalent[1]?
Do you want your Lua function definitions to look like this ...

<snip>

... to get type checking for function arguments and/or return values?

Nice!

[1] does a similar argument-checking thing.  It parses special LDoc comments (that LDoc now supports) and uses a hook, rather than a decorator (hooks are unfortunately very slow, but at least optional).

I think those tools have more chances of being successful if they reuse information that is already there or at least has other benefits besides type checking. It increases the motivation to actually write annotations, and maybe you can even detect outdated documentation during unit testing[*]. So reusing LDoc comments is a good idea, IMHO.

 Comment syntax is inspired by [2], which is also an argument checker, and there was a conversation about argument checking last year [3]

There is also this wiki page[4], and some time ago I implemented the typecheck decorator outlined here[5]. But what upset me was that none of my attempts at type checking could even handle the Lua standard library (especially table.insert( table, [pos,] value ) was #$!%..., and return values are not that easy either (e.g. somevalue _or_ nil,errormessage)). Btw., that's also the reason why I'm not entirely convinced that Luadoc's/LDoc's current comment format is the best fit for Lua.

I already knew about checks[2], and I like it because it requires little code, and probably is faster than most other attempts (although I would have merged the checks function and the checkers table into one functable[6] and returned it via require without setting a global). The custom type functions for checks and annotate should be compatible.

  [4]:  http://lua-users.org/wiki/LuaTypeChecking
  [5]:  http://lua-users.org/wiki/DecoratorsAndDocstrings
  [6]:  http://lua-users.org/wiki/FuncTables

Cheers,
Geoff

Philipp

[1] https://github.com/geoffleyland/argcheck
[2] https://github.com/SierraWireless/luasched/blob/master/c/checks.c
[3] http://lua-users.org/lists/lua-l/2012-10/msg00031.html

  [*]: Ahh, new idea: Unit testing using examples in the docstring ...