lua-users home
lua-l archive

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


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

> On Wed, Oct 24, 2012 at 10:29 AM, Geoff Leyland
> <geoff_leyland@fastmail.fm> wrote:
>> foo(
>> a, -- string
>> b) -- integer
> 
> Yeah, I support this pattern with the last comment _before_ the
> closing parens - should not be difficult to check for this case, which
> reads better anyhow.

Don't forget this:

function foo(a) -- this is a bit of an ambiguous way to document a

and

function foo(
 a, -- a really really
    -- long description
 b) -- and a short one

One thing that's needed is a convention to tell if the comment is intended as a type annotation (for now I'm using a colon):

function foo(
 a)  -- string: a description

Otherwise this:

function foo(
  a) -- I don't want to get this type-checked

gets a complaint that a is not of type I.  Type aliases could work?

function foo(
  a)  -- @?string|1..3

> Next release (soon!) will define the primitive types as tparam
> aliases, so @string, etc. (@int is interesting one, since you apply an
> additional custom constraint here, very useful)

Is it a good idea to prefix the aliases with an @?  It means you have to distinguish between @string (a type), @tparam (followed by a type) and @see (not a type).  All possible of course, but picking a different character would make it simpler.  I guess there's a fairly large body of code already using ldoc.

> What could work is if there's an argcheck option to run a preprocessed
> version, with explicit type asserts (they can all be on the same line
> as 'function' so no line number confusions)

That's an interesting and completely different approach!  I guess if we sort out what the comments are supposed to look like then we can have competing implementations,