lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]


On 24/10/2012, at 8:47 PM, steve donovan <steve.j.donovan@gmail.com> wrote:

> 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!

Thanks!

> Would be useful to harmonize with tools like LDoc

Absolutely.  I couldn't agree more.  It would be a disaster if it didn't.

(by the way, my preferred syntax for parameter annotations is inline with the arguments, to save repeating myself:

foo(
 a, -- string
 b) -- integer

Which LDoc *almost* supports.  I had a look at LDoc internals and got nowhere, so I pinged you on github.  If you can show me around I'll try to put together LDoc patches)
 
> 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.

I saw those in the LDoc manual, and it could be difficult if nonstandard aliases were defined, but standard ones would be good.  I guess argcheck could read the same config file as LDoc and get the same set of aliases?

> Because the truly cool thing is that it gives people _another_ good
> reason to use doc comments...

I know!  I've been gratuitously commenting code since I wrote it.  Trouble is, it's slooooow.  It should be possible to compile the checks after the first time around and that might help.

> 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!

At the moment it tries mt.__type, mt.__typename, mt.__typeinfo[type] (but not mt._name - I missed that!), then searches for globals and upvalues with the same name as the type and checks if they match the metatable.  You could easily make "type detectors" pluggable.

> Another approach is explicit type description, e.g {string...} is a
> table of strings, {name=string,age=int} is a structure, and so forth.

Yes, working out what this should look like would be well worthwhile.
I stole 1..5 for ranges from lapp, and I've been toying with the idea of going all Eiffel and contractual and allowing general constraints on parameters.  I don't know that there's a way to catch the return values of a function with a hook for postconditions though.

Cheers,
Geoff