How to document JavaScript/CoffeeScript data structures

Question

I am looking for a descriptive way to document the used data structures in my JavaScript application. I find it hard to get this done due to the dynamic character of JavaScript.

For instance, what could be a good way to tell, that a used variable distance is a two-dimensional array with length i and j and stores numbers between -1 and MAX_INT. I could think of something like this:

distance[i][j] = -1 <= n <= MAX_INT

What about an object which is used as a map/dictionary for certain data types, what about a two-dimensional array where the first element of an array defines other data then the rest, etc.

Of course, it is always possible to document these things in a text, I just thought, maybe there is a well known and used way to do this in a semiformal way.

Answer 1

Although it's not too widely adopted (yet?), there is a draft standard for JSON schema. I'm just learning it myself but you could write a schema for your two-dimensional array (wrapped inside of an object) as:

{
    "description":"Two dimensional array of numbers",
    "type":"object",
    "properties":{
        "two-d-array":{
            "description":"columns",
            "type":"array",
            "items":{
                "description":"rows",
                "type":"array",
                "items": {
                   "description":"values",
                   "type":"number",
                   "minimum":-1,
                   "maximum":Number.MAX_VALUE
                }
            }
        }
    }
}

or simply:

{
    "type":"array",
    "items":{
        "type":"array",
        "items": {
            "type":"number",
            "minimum":-1,
            "maximum":Number.MAX_VALUE
        }
    }
}

There is no CoffeeScript implementation that I know of, but there is a list of several JavaScript validators here. I'm playing with the one that's written by the spec authors called (simply enough) json-schema and I like it well enough calling it from CoffeeScript.