Re: Documenting data structures

[Hisham <h@...>]

On 21 July 2015 at 19:43, Jorge <xxopxe@gmail.com> wrote:
> Hi to everyone.
>
> A question, what do you people use for documenting datastructures? Say, you
> program has a table that maps string to arrays of numbers, or have a
> function that receive a table with specific set of keys expected, and stuff
> like that.
>
> Ideally, some portable/standard/intuitive option would be great, like a
> pseudocode but for data structures. Alternatively, I'm aware there are some
> data description formats for the typed variations of lua, perhaps some of
> that could be used?

That's precisely what I was going to suggest. Typed Lua supports type
definitions in separate .tld files. This is the typing of LuaSocket's
"socket" module:

https://github.com/andremm/typedlua/blob/master/examples/luasocket/socket.tld

The format takes a bit getting used to (literal table keys must be
written in quotes to differentiate them from type names, and I think
_some_ of these parentheses could go away in a future version) but in
my experience I found them to be a nice way of documenting tables
(haven't used them in big projects yet since the Typed Lua compiler is
still alpha, but writing down table specifications felt good).

-- Hisham