Documenting data structures

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Documenting data structures

Jorge Visca
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?

Jorge


Reply | Threaded
Open this post in threaded view
|

Re: Documenting data structures

Javier Guerra Giraldez
On Tue, Jul 21, 2015 at 5:43 PM, Jorge <[hidden email]> wrote:
> A question, what do you people use for documenting datastructures?


UML?

/duck & cover

--
Javier

Reply | Threaded
Open this post in threaded view
|

Re: Documenting data structures

Andrew Starks
In reply to this post by Jorge Visca


On Tuesday, July 21, 2015, Jorge <[hidden email]> 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?

Jorge



There is UML and its various profiles. ContTeX or LuaLaTeX, plus PGF/TiKz  with the... TiKzUML(?) package works really well for me. I'm having troubles with the googles right now, but I can provide links, if you desire. 

TiKz works well for developing mini-DSL/notations that can work for this purpose, if UML is not to your liking. 

LaTeX and friends can be a large stack to swallow, but it's very well documented. 

-Andrew
Reply | Threaded
Open this post in threaded view
|

Re: Documenting data structures

Petite Abeille
In reply to this post by Javier Guerra Giraldez

> On Jul 22, 2015, at 12:47 AM, Javier Guerra Giraldez <[hidden email]> wrote:
>
> /duck & cover

UML: The Positive Spin
https://archive.eiffel.com/doc/manuals/technology/bmarticles/uml/page.html
Reply | Threaded
Open this post in threaded view
|

Re: Documenting data structures

Jorge Visca
In reply to this post by Andrew Starks
On 07/21/2015 10:03 PM, Andrew Starks wrote:
> There is UML and its various profiles.
> ...
> LaTeX and friends can be a large stack to swallow, but it's very well
> documented.

I have no fear of LaTeX, no. In fact, this is one of the motivations for
this "request for comments": I usually rely on the algorithmic package
for pseudocode, but can't find a common notation for expressing anything
  beyond an array. In one particular case, I would like to have a
standard notation to express a Table and a Set to do something like:

\STATE $V$ : SET OF { message, nodes $:$ SET OF $[$Node$]$ \}
...
\FORALL{$v$ IN V}
   \IF{ $n$ IN $v$.nodes}
...

So, it's not for very complex models, just a tool to better explain an
algorithm. In reality, my pseudocodes end looking like pseudo-Lua, which
is weird (or not).

On the UML, to be honest I had completely forgot such a thing exists. I
was happy. Thanks you all.

After a quick perusal of the UML profiles I do not find anything
adequate. For my use (casual documenting) UML is way too complex and non
intuitive. Whenever I see at a UML diagram I do not know what I'm
looking at ("why this arrow has a black dot at the root and this one is
purple?"). I find plain old Entity-Relation diagrams easier to read, but
even they are not very helpful when you're trying to describe an
algorithm (how do you express that you enumerate all the associated in a
1 to n relationship?).

In my code I end documenting writing down a sample instance of what is
supposed to be there, like:

-- { {color={1,2,3}, x=0, y=0}, ... }
local V



Jorge


Reply | Threaded
Open this post in threaded view
|

Re: Documenting data structures

Hisham
In reply to this post by Jorge Visca
On 21 July 2015 at 19:43, Jorge <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Documenting data structures

Dirk Laurie-2
In reply to this post by Jorge Visca
2015-07-22 19:59 GMT+02:00 Jorge <[hidden email]>:
> I have no fear of LaTeX, no.

Can't LuaTeX and friends (LuaLaTeX, ConTeXt) do what you need?
<http://www.luatex.org>

Reply | Threaded
Open this post in threaded view
|

Re: Documenting data structures

Jorge Visca
In reply to this post by Hisham
On 07/22/2015 03:07 PM, Hisham wrote:
> 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

That looks actually very interesting, thanks for the pointer. I think
I'll show some simple examples ton non-Lua types (ha!) and ask them if
they can guess the structure.

Jorge