How to document JavaScript / CoffeeScript structures

Question

I am looking for a descriptive way to document the data structures used in my JavaScript application. I find it difficult to do this due to the dynamic nature of JavaScript.

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

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

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

Of course, you can always document these things in the text, I just thought maybe there is a well-known and used way to do this in a semi-formal way.

Answer 1

Although not widely accepted (yet?), There is a draft standard for the JSON scheme . I just study it myself, but you can write a circuit for your two-dimensional array (wrapped inside an object) as follows:

 { "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 play with what the authors of the specs (quite simply) json-schema wrote, and I like it well enough, calling it from CoffeeScript.

Answer 2

What I usually do in my JavaScript when I replicate many data models is to write out that their class definition will be in the comments. I am not sure if this is what you had in mind with your question.

 // JavaScript Class jsHomeLocation // jsHomeLocation{ // string name // string address // } var jsHomeLocation = {}; jsHomeLocation.name = "Travis"; jsHomeLocation.address = "California"; 

You can also use javascript objects to track example information, a two-dimensional array

 var distanceData = {}; distanceData.type = "two-dimensional array"; distanceData.length = i * j; distanceData.min = -1; distanceData.max = MAX_INT;