Cómo documentar las estructuras de datos JavaScript/CoffeeScript

Question

Estoy buscando una forma descriptiva para documentar las estructuras de datos usadas en mi aplicación de JavaScript. Me resulta difícil hacer esto debido al carácter dinámico de JavaScript.

Por ejemplo, lo que podría ser una buena manera de decir, que un usado variable de distancia es una matriz de dos dimensiones con una longitud de i y j números y almacena entre -1 y MAX_INT. Lo que podía pensar algo como esto:

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

¿Qué hay de un objeto que se utiliza como un mapa/Diccionario para ciertos tipos de datos, ¿qué pasa con una matriz de dos dimensiones, donde el primer elemento de una matriz define otra datos luego el resto, etc.

Por supuesto, siempre es posible documentar estas cosas en un texto, solo pensé que tal vez haya una manera conocida y usada para hacer esto de forma semiformal.

Answer 1

Aunque no es demasiado ampliamente adoptado (¿todavía?), Hay una draft standard for JSON schema. Estoy aprendiendo a mí mismo, sino que podría escribir un esquema para su matriz bidimensional (envuelto en el interior de un objeto) como:

{ 
    "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 
       } 
      } 
     } 
    } 
} 

o simplemente:

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

No hay ninguna aplicación CoffeeScript que yo sepa, pero hay una lista de varios validadores de JavaScript here. Estoy jugando con el que está escrito por los autores de las especificaciones llamado (simplemente suficiente) json-schema y me gusta lo bastante como llamarlo desde CoffeeScript.

Answer 2

Lo que tiendo a hacer en mi JavaScript cuando estoy replicando una gran cantidad de modelos de datos es escribir cuál sería su definición de clase en los comentarios. No estoy seguro de si esto es lo que quisiste decir con tu pregunta.

// JavaScript Class jsHomeLocation 
// jsHomeLocation{ 
// string name 
// string address 
// } 

var jsHomeLocation = {}; 
jsHomeLocation.name = "Travis"; 
jsHomeLocation.address = "California"; 

También es posible usar los objetos JavaScript para rastrear la información del ejemplo, una matriz bidimensional

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