How to document JavaScript/CoffeeScript data structures
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.
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.
What I tend to do in my JavaScript when I am replicating a lot of data models is to write out what their class definition would be in comments. I am not sure if this is what you meant with your question.
// JavaScript Class jsHomeLocation
// jsHomeLocation{
// string name
// string address
// }
var jsHomeLocation = {};
jsHomeLocation.name = "Travis";
jsHomeLocation.address = "California";
You could also use javascript objects to track the information of the example, a two-dimensional array
var distanceData = {};
distanceData.type = "two-dimensional array";
distanceData.length = i * j;
distanceData.min = -1;
distanceData.max = MAX_INT;
上一篇: Symfony2中的战略模式