On Tue, Oct 23, 2012 at 7:58 PM, Geoff Leyland
<geoff_leyland@fastmail.fm> wrote:
It's not as polished as the Sierra solution yet, and currently quite slow (as hooks in Lua tend to be), but I like that the comments double as documentation comments.
Man, that really is a cool dual-use of doc comments!
Would be useful to harmonize with tools like LDoc - @tparam of course
is a LDoc extension directly inspired by Sierra Wireless' contribution
to that project. LDoc makes it straightforward to add aliases, so
that you can say '@string' rather than '@tparam string', and these are
useful enough that I think they should come with the kit.
Because the truly cool thing is that it gives people _another_ good
reason to use doc comments....
Beyond primitive types we get the 'type description' problem. Say
someone defines a type Foo, somewhere. A useful discipline is to use
named types as much as possible in code, because it's easier to
document.
But checking an argument of type 'Foo' requires some assumptions about
how objects are organized - they have a metatable yes, but where to
put the type's name? E.g. in Penlight the convention is that
getmetatable(obj)._name will be the name of the class, but this only
happens automatically if using the 'class.Frodo()' syntax. So even in
one library it's not a guarantee!
Another approach is explicit type description, e.g {string...} is a
table of strings, {name=string,age=int} is a structure, and so forth.
