Re: Online Help in eLua?

Posted by BogdanM on
URL: http://elua-development.15.s1.nabble.com/Online-Help-in-eLua-tp2456949p2457216.html

On Tue, Mar 10, 2009 at 8:17 PM, James Snyder <[hidden email]> wrote:

I'm not suggesting this for the current release, but I was playing around with enumerating the tables for our hardware modules and it gave me a thought.

Is there a plan or interest in using metatables to provide simple help information for module methods?  I know something like this could always quickly grow into something that consumes many kilobytes of space, but what about just optional really short descriptions, like the following:

> help(adc.setclock)
setclock( id, clock, [timer_id] ) -- set clock and timer_id for channel id

or even just the parameter list:
> help(adc.setclock)
setclock( id, clock, [timer_id] )

Doing some sort of programmatic generation of the list, I think, would be key to make it maintainable.

Maybe this could even be extended so that the documentation could be kept inline in the module source and have a script that will take take these elements and populate the webbook docs.

Hmmm, I was thinking about something precisely between these lines. Have a common documentation format (XML?) in which every function has two descriptions: a short description and a long description. The short one (or both, this should be selectable) would go inside eLua, while both of them would always go in webbook.
Your idea is very good, and inline with eLua's design principle of "run everything from the board". If we run everything from the board, having "on-line help" would certainly be a big help and a nice addition. I'm worried about flash consumption, but it doesn't have to be a problem. We could save the help in a file, in a simple format, and then load it either from internal ROMFS (if there's space there), or from SD, or from another ROMFS that leaves in a separate SPI flash, or ... well, you got the picture :) I like this idea a lot.
Excellent timing James! And thanks for mentioning this _before_ I even started to rewrite the API docs. Now I'll probably make them XML and write a simple Lua script to transform that into either webbook or "eLua format" (TBD).

Best,
Bogdan

PS. I have _got_ to finish those pesky docs already !!! I started to type ESC :w even when writing mails in gmail :|

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev