Re: [ANN] Interactive module help based on LDoc

[steve donovan <steve.j.donovan@...>]

On Tue, Mar 26, 2013 at 8:35 AM, Dirk Laurie <dirk.laurie@gmail.com> wrote:
> I've turned it into a one-file module coded in Lua. You save it
> somewhere in your file path under a name of your own choosing.
> Say you have called it "help.lua". Then use it as follows:

Just to point out the coolest thing: it works with any modules which
have docstrings, even if they aren't in LuaDoc format. E.g. if we pull
in Penlight in the lazy way (which is fine for interactive work):

> require 'pl'
> help(utils)
Contents: _VERSION add_function_factory array_tostring assert_arg
    assert_string bind1 bind2 choose dir_separator escape execute fprintf
    function_arg import is_callable is_integer is_type load lua51 memoize
    on_error patterns printf quit raise readfile readlines split splitv
    stdmt string_lambda type writefile
> help(utils.readfile)
--- return the contents of a file as a string
-- @param filename The file path
-- @param is_bin open in binary mode
-- @return file contents

For built-in libraries, one obviously doesn't get so much information:

> help(math)
Contents: abs acos asin atan atan2 ceil cos cosh deg exp floor fmod
    frexp huge ldexp log log10 max min mod modf pi pow rad random randomseed
    sin sinh sqrt tan tanh
> help(math.sqrt)
Precompiled C function

But ... it would not be difficult to do better. LDoc comes with LuaDoc
files for the standard libraries, which I copied from Mitchell's
Textadept project:

https://github.com/stevedonovan/LDoc/tree/master/ldoc/builtin

Using the lookup tables in globals.lua in that directory, ihelp could
present help for these built-in functions.

steve d.