[ANN]otate

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

[ANN]otate

Philipp Janda
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 ...

   example = annotate[=[
     This example function does something really useful.

     example( input [, flags, ...] ) ==> table        -- on success
                                     ==> nil, string  -- in case of error
         input: string/function   -- filename or function producing input
         flags: table             -- set of flags
         ...  : (table/string)*   -- more flags

     Some more text describing function `example` ...
   ]=] ..
   function( input, flags, ... )
     -- ...
   end

... to get type checking for function arguments and/or return values?
Then maybe this module is for you. You can get it at your nearest rocks
server or on github[2], documentation is here[3], license is MIT.

   [1]:  http://lua-users.org/wiki/DecoratorsAndDocstrings
   [2]:  https://github.com/siffiejoe/lua-annotate/
   [3]:  http://siffiejoe.github.io/lua-annotate/

If you have a great new idea what to do with docstrings, annotate allows
you to register callbacks to implement those ideas without conflicts.

/marketing mode off

Thx,
Philipp


Reply | Threaded
Open this post in threaded view
|

Re: [ANN]otate

Dirk Laurie-2
2013/4/25 Philipp Janda <[hidden email]>:
> 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 ...
>
>   example = annotate[=[
>   Some more text describing function `example` ...
>   ]=] ..
>   function( input, flags, ... )

The OP of the one-message thread

    http://lua-users.org/lists/lua-l/2010-10/msg00612.html

would probably like to hear about this.

A search on "docstring" on the list archive also shows:

    http://lua-users.org/lists/lua-l/2013-03/msg00775.html

That's an interactive help system based on the LDoc notation.

Reply | Threaded
Open this post in threaded view
|

Re: [ANN]otate

Geoff Leyland
In reply to this post by Philipp Janda
Hi Phillip,

On 25/04/2013, at 10:02 AM, Philipp Janda <[hidden email]> 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).  Comment syntax is inspired by [2], which is also an argument checker, and there was a conversation about argument checking last year [3]

Cheers,
Geoff

[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


Reply | Threaded
Open this post in threaded view
|

Re: [ANN]otate

Philipp Janda
In reply to this post by Dirk Laurie-2
Am 25.04.2013 07:22 schröbte Dirk Laurie:
>
> A search on "docstring" on the list archive also shows:
>
>      http://lua-users.org/lists/lua-l/2013-03/msg00775.html
>
> That's an interactive help system based on the LDoc notation.
>

Ah, I've been looking for a recent example of an interactive help
system. I only found asklua and luahelp, which both are still Lua 5.1
only, and therefore seem to be more or less abandoned.

I pushed a simple help module which can fallback to another help system
like yours in case no docstring is available:

     local help = require( "annotate.help"):wrap( require( "help" ) )
     --                     ^ my help                       ^ your help
     local annotate = require( "annotate" )

     example1 = annotate[[annotate docstring]] .. function() end

     --- LDoc docstring
     -- for function example2
     function example2() end

     help( example1 )
     help( example2 )


One other obvious thing to do would be an offline documentation
generator, but Steve more or less promised (:-p) to write an LDoc-plugin
for annotate, so I will sit on my hands for a while ...

Other ideas floating in my head are general pre-/postconditions, design
by contract like in Eiffel, and function call logging/tracing (which are
not that useful in user documentation, I admit). Docstrings *have* to be
useful to make up for the additional memory overhead. So I'm open to
suggestions ...

Philipp




Reply | Threaded
Open this post in threaded view
|

Re: [ANN]otate

Philipp Janda
In reply to this post by Geoff Leyland
Am 25.04.2013 08:29 schröbte Geoff Leyland:
> Hi Phillip,

Hi!

>
> On 25/04/2013, at 10:02 AM, Philipp Janda <[hidden email]> 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 ...




Reply | Threaded
Open this post in threaded view
|

Re: [ANN]otate

oliver-2
  [*]: 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.



On Thu, Apr 25, 2013 at 8:43 AM, Philipp Janda <[hidden email]> wrote:
Am <a href="tel:25.04.2013%2008" value="+12504201308" target="_blank">25.04.2013 08:29 schröbte Geoff Leyland:
Hi Phillip,

Hi!



On 25/04/2013, at 10:02 AM, Philipp Janda <[hidden email]> 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   [*]: Ahh, new idea: Unit testing using examples in the docstring ...





Reply | Threaded
Open this post in threaded view
|

Re: [ANN]otate

Dirk Laurie-2
2013/4/27 oliver <[hidden email]>:
>>   [*]: 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

This should not be too hard to do in Lua, but does sit better with a format like

--[[---
...
]]

than with the current LDoc format. Still, not hard to teach LDoc to accept that
as an alternative.

Reply | Threaded
Open this post in threaded view
|

Re: [ANN]otate

Geoff Leyland
In reply to this post by Philipp Janda
On 26/04/2013, at 12:43 AM, Philipp Janda <[hidden email]> wrote:

>  return values are not that easy either

Handling return values at all seems pretty hard with a hook (anyone got any bright ideas?), so it's either a decorator as you use, or writing a tricky loader that parses doc comments and adds code, as Steve suggested at one stage.

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

It's an idea I really like.  [1] does something similar: it looks for <pre> blocks in markdown files (i.e. lines with four spaces in front of them) and tries to execute them, checking that the results are the same as indicated by comments in the same style as in PiL.  It means that examples in the documentation are always correct.  At one stage I thought about doing the same thing for TeX (but then I didn't).

Cheers,
Geoff

[1] https://github.com/geoffleyland/rima/blob/master/lua/test/doctest.lua