Re: [ANN]otate

[Philipp Janda <siffiejoe@...>]

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