Come documentare gli oggetti di configurazione JavaScript in Visual Studio Intellisense

Question

Ho utilizzato JavaScript di Visual Studio Intellisense functionality per un po 'di tempo e sono stato per lo più felice con quanto fornisce suggerimenti per API standard, ma ho riscontrato che non riesco a ottenere Visual Studio capire gli oggetti di configurazione (cioè un singolo oggetto con più proprietà opzionali o richieste come argomento di una funzione).

Il official JSDoc syntax suggerisce che se un parametro dovrebbe avere proprietà, si crea una linea separata @param per ciascuno e per utilizzare la notazione del punto:

/** 
* @param {Object} config 
* @param {String} config.name 
* @param {Number} config.gold 
*/ 
function do_it(config) { ... } 

Tuttavia, Visual Studio non riconosce questo - rende config , config.name e config.gold come tre parametri di primo livello separati.

Peggio ancora, la funzionalità di completamento automatico all'interno del corpo del metodo non riconosce i parametri o, tanto meno loro tipi:

L'unica soluzione che sembra venire anche vicino a Visual Studio è quello di scrivere funzioni di costruzione mai chiamate con documentazione appropriata (@constructor e @property tag), il che mi fa scrivere un sacco di codice morto e anche andare contro la mentalità senza classe di JavaScript (che è la ragione per cui io se gli oggetti di configurazione sono in primo luogo). Non mi lascia nemmeno scrivere l'oggetto di configurazione!

Non solo, ma so anche che Visual Studio non ne ha bisogno. Ad esempio, quando ho scritto una chiamata a this library function, è stato in grado di capire che l'oggetto argomento ha bisogno di proprietà chiamate id, source e target e ha suggerito quei nomi quando ho creato un oggetto letterale per l'argomento della funzione - e senza linea singola di documentazione. Presumibilmente, è venuto dal semplice fatto che essi erano utilizzato:

Certo, il metodo non generare eccezioni se queste proprietà non sono l'oggetto e non sono del tipo corretto, ma ancora. EDIT: E di recente sono riuscito a replicare l'effetto nel mio codice in qualche modo con i parametri letterali dell'oggetto: ho chiamato una funzione con un oggetto ben definito e mi ha dato suggerimenti Intellisense quando ho richiamato la funzione altrove in il mio codice Ma non ho ancora informazioni di tipo o accesso semantico all'interno del corpo della funzione.

Visual Studio capisce ovviamente il concetto di oggetti di configurazione e sta facendo un po 'di logica per fornire proprietà suggerite. Cos'è questo algoritmo? E come posso sfruttarlo senza manomettere il mio codice?

Answer 1

Si sta utilizzando correct JSDoc syntax, ma a oggi Visual Studio non crea semplicemente l'IntelliSense corretto per gli oggetti parametro con proprietà denominate.Non ci sono ancora altro modo per aggirare questo diverso da quello che si fa riferimento a, ma si può descrivere l'oggetto config a posto e evitare di scrivere codice morto come lei ha ricordato come questo:

/** 
* @typedef {object} TestConfig 
* @property {string} name 
* @property {number} gold 
*//** 
* @param {TestConfig} config 
*/ 
function test(config) { 

} 

Dal momento che stiamo solo usando questo oggetto per documentazione e scopi AutoComplete non abbiamo bisogno di codificarlo effettivamente. Questo non è molto più dettagliato della sintassi originale e ha il vantaggio di avere anche l'oggetto di configurazione documentato.

Sulla seconda domanda, IntelliSense che è possibile visualizzare per la libreria sigma.js deriva dall'analisi del corpo del codice funzione stesso, non dai commenti JSDoc. Ecco perché puoi ancora usarlo quando aggiungi la build miniata "sigma.min.js" al tuo progetto, dove i commenti sono stati rimossi.

È possibile verificare questo convalida dei parametri aggiungendo simile a quello nel library function (anche se l'accesso ai config.name o config.gold in qualsiasi altro modo sarà anche produrre lo stesso risultato):

function do_it(config) { 
    if (Object(config) !== config || arguments.length !== 1) throw 'do_it: wrong arguments.'; 
    if (typeof config.name !== 'string') throw 'config must have a name string field.'; 
    if (typeof config.gold !== 'number') throw 'config must have a gold number field.'; 
    ... 
} 

risultati in:

In modo simile, una volta fornite le informazioni sufficienti verrà dedotto il tipo corretto: