I have often the same problem when using complex data structures (HoH, HoA, generally /([HA]o)+[HA]/): when passing data structures to functions or returning data structures, how do you document the form of data to the user of the function?
Perhaps the problem is an indication of the ad hoc nature of the data structures, but suppose you have a function that returns
Now, one way I am inclined to document this would be to use straight Perl syntax in describing an "abstracted" item in the data structure, meaning that the parts that can vary are variables:
Here the ellipsis means that the substructure contains identical entries where the parameterized parts (variables) vary. Literal names or values would be just those: literals. The benefit of this is that you can now refer to particular values in the data structure simply by using the variable name (such as $id) in describing what they actually contain. Another benefit is that you can use this "template" in traversing the data structure or accessing values.
However, given complex enough data structures, this will be unwieldy to both write and read. Besides this, unless the values are identical in the above, $val should in fact be two different variables, signifying that they do not depend on each other (while $id could be the same, since the same values occur in both 'changes' and 'originals' hashes). Larger data structure means that there will be even more points where you must name the varying values.
Surely there must be better ways. How do you do it?