Re: Documenting data structures

[Jorge <xxopxe@...>]

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