Exp Lua

wiki

ExpLua is both a code comment format and a tool for extracting said comments and exporting HTML, LaTeX, and whatnot. It is freely available for use under the same License as the Lua project, with the usual disclaimers.

The latest explua tarball can be found here at the Wiki: Files:wiki_insecure/users/miller/explua.tar.gz Be warned that this is a public site and hence the code is inherently untrusted. First and foremost, there should only be lua files inside the package.

An example of LaTeX (well, later converted to PS using my own macros, etc) content can be found at Files:wiki_insecure/users/miller/concur.ps.gz.

This is a project still at embrionary stages. I'm mostly uploading this here in response to Reuben's email. In the following section, I attach my reply to his message. Feel free to add comments, questions or opinions as you see fit. The output-generation is currently using lots of small concatenations, which is slow, and I know it. It shall be changed. --Pedro

On Sunday 19 October 2003 20:32, Reuben Thomas wrote:
> I intend to fix on a system to use soonish (to make the libraries more
> easily usable), so it would be nice to know how ExpLua works even if it's
> not ready yet.

Okay. I've been working on the system as a whole in an adaptive, progressive, iterative refining methodology -- i.e., sometimes kludging for twenty minutes, sometimes designing/building/testing whole bunches of the stuff throughout the night -- mostly geared towards automatically documenting functions and modules for my thesis (which has a whole lot of them, and I didn't feel like writing stuff twice and maintaining them in both versions).

I started out by trying to use other systems available (e.g, LuaDoc?, JavaDoc?, and even literate programming), but found that they had a tendency to get way too much on the way of my bad programming habits. Sadly, they weren't strong and satisfying enough for me to drop my weakness and start designing correctly -- I would just get tired of typing the @param tags and stop commenting altogether.

So I figured I wanted a commenting system that was simpler to type when you're programming and easy to read even if you don't understand the specific comment format. I chose a system of glyphs as thus:

For the whole file:

--| Begins a module/file comment, e.g., "this file does *this*".
--by Pedro Miller Rabinovitch <miller@inf.puc-rio.br>
--$Id: myfile.lua,v 1.12 2003/10/17 00:13:56 miller Exp $
--TODO lots of stuff.

(Both --by and --TODO can be abbreviated to --b and --T)

Preceding each function:

--% This is the purpose of the function, i.e., what it *does*.
--- And this is the second line, which will concatenated to
--- the others.
--@ first (string) Text of the first parameter
--@ what (table) The second parameter is the table used for an
--- example
--@ [...] (any) Optional parameters to the called whatever
--: (number) Number of whatevers done or nil if an error occured
function Module:MyFunction( first, what, ... )

(I still haven't decided on an 'alternative' format, e.g., (number|nil), (number, nil). Multiple return values are not allowed in the current implementation, but that will change ASAP.)

That's basically it for now. There's some more stuff I'm planning ahead on (like --& and --. for important tables and fields, respectively, and I need I'm also going to need some kind of type-definition later on), but the important stuff is there.

The great thing about this is, now that it's become so simple, I'm documenting a lot more my code. And the more documentation I have, the more I want to extract it and generate stuff...

'nuff said. I had more to discuss here, but ain't got the time right now.

RecentChanges · preferences
edit · history
Last edited October 20, 2003 2:41 pm GMT (diff)