Quelle est la bonne façon de documenter les rappels avec jsdoc?
J'ai passé pas mal de temps à parcourir Internet à la recherche du meilleur moyen de documenter correctement les rappels avec jsdoc, mais malheureusement, je n'en ai pas encore trouvé un excellent.
Voici ma question:
J'écris une bibliothèque Node.js pour les développeurs. Cette bibliothèque fournit plusieurs classes, fonctions et méthodes avec lesquelles les développeurs travailleront.
Afin de rendre mon code clair et compréhensible, ainsi que pour (espérons-le) générer automatiquement de la documentation API à l'avenir, j'ai commencé à utiliser jsdoc dans mon code pour auto-documenter ce qui se passe.
Disons que je définis une fonction comme la suivante:
function addStuff(x, y, callback) {
callback(x+y);
});
En utilisant jsdoc, je documente actuellement cette fonction comme suit:
/**
* Add two numbers together, then pass the results to a callback function.
*
* @function addStuff
* @param {int} x - An integer.
* @param {int} y - An integer.
* @param {function} callback - A callback to run whose signature is (sum), where
* sum is an integer.
*/
function addStuff(x, y, callback) {
callback(x+y);
});
J'ai l'impression que la solution ci-dessus est un peu hack-ish, car il n'y a aucun moyen pour moi de spécifier en termes absolus ce que la fonction de rappel devrait accepter.
Idéalement, j'aimerais faire quelque chose comme:
/**
* Add two numbers together, then pass the results to a callback function.
*
* @function addStuff
* @param {int} x - An integer.
* @param {int} y - An integer.
* @param {callback} callback - A callback to run.
* @param {int} callback.sum - An integer.
*/
function addStuff(x, y, callback) {
callback(x+y);
});
Ce qui précède semble me permettre de transmettre plus simplement ce que mon rappel doit accepter. Cela a-t-il du sens?
Je suppose que ma question est simple: quelle est la meilleure façon de documenter clairement mes fonctions de rappel avec jsdoc?
Merci pour votre temps.
JSDoc 3 a une @ balise de rappel à cet effet. Voici un exemple d'utilisation:
/**
* Callback for adding two numbers.
*
* @callback addStuffCallback
* @param {int} sum - An integer.
*/
/**
* Add two numbers together, then pass the results to a callback function.
*
* @param {int} x - An integer.
* @param {int} y - An integer.
* @param {addStuffCallback} callback - A callback to run.
*/
function addStuff(x, y, callback) {
callback(x+y);
}
Une autre possibilité consiste à décrire la valeur passée au rappel de cette façon:
/**
* Add two numbers together, then pass the results to a callback function.
*
* @function addStuff
* @param {int} x - An integer.
* @param {int} y - An integer.
* @param {function(int)} callback - A callback to run whose signature is (sum), where
* sum is an integer.
*/
function addStuff(x, y, callback) {
callback(x+y);
});
Pour documenter le type de retour du rappel, utilisez @param {function(int):string}.
Solution pour que VSCode le comprenne
/**
* @typedef {function(FpsInfo)} fpsCallback
* @callback fpsCallback
* @param {FpsInfo} fps Fps info object
*/
/**
* @typedef {Object} FpsInfo
* @property {number} fps The calculated frames per second
* @property {number} jitter The absolute difference since the last calculated fps
* @property {number} elapsed Milliseconds ellapsed since the last computation
* @property {number} frames Number of frames since the last computation
* @property {number} trigger Next computation will happen at this amount of frames
*/
/**
* FPS Meter - Returns a function that is used to compute the framerate without the overhead of updating the DOM every frame.
* @param {fpsCallback} callback Callback fired every time the FPS is computed
* @param {number} [refreshRate=1] Refresh rate which the fps is computed and the callback is fired (0 to compute every frame, not recommended)
* @returns {function} Returns a function that should be called on every the loop tick
* @author Victor B - www.vitim.us - github.com/victornpb/fpsMeter
*/
function createFpsMeter(callback, refreshRate = 1) {
// ...
}
