jsdoc et vscode: Documenter une fonction transmise en tant qu'argument à une autre fonction

Question

J'essaye de documenter les paramètres d'entrée à une fonction en javascript, mais je ne peux pas travailler sur la façon de le faire dans jsdoc.

J'ai regardé la documentation de jsdoc qui suggère que l'utilisation du commentaire @callback est ce qui est requis, mais Visual Studio Code (vscode) ne le met pas en évidence selon la capture d'écran.

Le intellisense pour le paramètre location montre qu'il est de type any plutôt que du type locator (une fonction avec un paramètre de id qui renvoie un Location).

code exemple qui montre une fonction appel d'une fonction passée en paramètre:

class Location { 
    constructor(position, count) { 
    this.position = position; 
    this.count = count; 
    } 
} 

const items = { 
    'USB Cable': new Location('Desk Drawer', 123), 
    Keyboard: new Location('Desk Surface', 1), 
}; 

/** 
* A locater. 
* @param {string} id 
* @returns {Location} 
*/ 
const locaterA = id => items[id]; 

/** 
* Finds the item by its unique id. 
* @callback locater 
* @param {string} id 
* @returns {Location} 
*/ 

/** 
* Attempt to find the item with the given locater. 
* @param {string} id 
* @param {locater} locater 
*/ 
const locate = (id, locater) => locater(id); 

const result = locate('USB Cable', locaterA); 

console.log(result); 

Est-ce un problème avec ce que je fais, vsdoc ne supportant pas le cas d'utilisation ou vscode ne pas le soutenir?

Answer 1

IntelliSense de Vscode ne prend pas en charge @callback. Il est suivi ici: https://github.com/Microsoft/TypeScript/issues/7515.

Pour contourner ce problème pratique, vous pouvez utiliser @typedef:

/** 
* Finds the item by its unique id. 
* @typedef {function(string): Location} Locater 
*/ 

/** 
* Attempt to find the item with the given locater. 
* @param {string} id 
* @param {Locater} locater 
*/ 
const locate = (id, locater) => locater(id); 

Answer 2

Il semble que vous l'utilisiez correctement, par JSDoc lui-même. Cependant, il semble que Visual Studio peut supporter qu'un sous-ensemble limité de JSDoc, qui ne comprend pas @callback: https://msdn.microsoft.com/en-us/library/mt162307.aspx

Je n'ai pas Visual Studio à portée de main, mais vous pouvez essayer le style de fermeture Google, qui est de faire comme ceci:

@param { function(string) : number } locator 

Ceci dit que c'est une fonction qui prend une chaîne, et retourne un nombre.

Vous pouvez trouver cette documentation ici: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler (recherchez "Type de retour de fonction" pour accéder à la section correspondante).

J'ai remarqué avec JetBrains qu'au moins, il supporte cette syntaxe.