Documenter source au format jsDoc

[jsys]

Bonjour,
J’essai de documenter au mieux un source JS dans Webstorm pour qu’il me détecte mes erreurs. Exemple :

/**
* Un point
* @param {number} x
* @param {number} y
*/
function point(x,y) {
  return {x:x, y:y};
}

/**
* Un rectangle
* @param {point} p1 <= Là ça ne marche pas
* @param {point} p2
*/
function rectangle(p1, p2) {
  return {x:p1.x, y:p1.y, l:p2.x-p1.x, h:p2.y-p1.y};
}

Comment indiquer que {point} est le résultat de la fonction point() car jsDoc ne comprend pas là :(
J’ai consulté la doc sans succès. Un pti exemple vaut une longue doc :-)
Un passage à ES6 résoudrait aussi le problème.

[Joris]

J’ai pas exploré JsDoc plus que ça mais la comme ça je dirais qu’il faudrait que point ait une définition dans jsDoc pour être reconnu comme un type.
je vois que ES6 ou Typescript pour faire ça bien avec une approche native plutôt que de compter sur des metadata et un IDE pour palier

[Haeresis]

Bonjour @jsys,

Dans ton exemple, point n’existe pas en tant que type car ce n’est qu’une fonction. La documentation correcte serait donc :

/**
 * Un point
 * @param   {number} x La coordonnée x.
 * @param   {number} y La coordonnée y.
 * @returns {Object}   Le point.
 */
function point(x,y) {
    return {x:x, y:y};
}

/**
 * Un rectangle
 * @param   {Object} p1 Le point supérieur gauche.
 * @param   {Object} p2 Le point inférieur droit.
 * @returns {Object}    Le Rectangle.
 */
function rectangle(p1, p2) {
    return {x:p1.x, y:p1.y, l:p2.x-p1.x, h:p2.y-p1.y};
}

Ce que tu souhaites en réalité c’est que ton point et ton rectangle soit un type d’objet. Qu’il utilise donc le prototype de Object. Il va falloir instancier tes objets pour faire cela.

Point n’est ni un type primitif, n’y un Object. Il va donc falloir le créer. Par convention, si ce n’est pas un type primitif (number, boolean, string) ou vide (null, undefined) il doit s’écrire avec une majuscule.

Pour définir l’objet {Point} il faut faire cela :

test.js

/**
 * Un point
 * @param {number} x La coordonnée x.
 * @param {number} y La coordonnée y.
 * @this  {Point}    Le point.
 */
function point(x,y) {

    /**
     * Un objet point.
     * @typedef  {Object} Point
     * @property {number} x     La coordonnée x.
     * @property {number} y     La coordonnée y.
     */
    this.x = x;
    this.y = y;
}

/**
 * Un rectangle
 * @param {Point}     p1 Le point supérieur gauche.
 * @param {Point}     p2 Le point inférieur droit.
 * return {Rectangle}    Le Rectangle.
 */
function rectangle(p1, p2) {

    /**
     * Un objet rectangle.
     * @typedef  {Object} Rectangle
     * @property {number} x         La coordonnée x.
     * @property {number} y         La coordonnée y.
     * @property {number} l         La coordonnée y.
     * @property {number} h         La coordonnée y.
     */
    this.x = p1.x;
    this.y = p1.y;
    this.l = p2.x - p1.x;
    this.h = p2.y - p1.y;
}

En utilisant la commande

jsdoc test.js

Tu généreras une doc au poil. Je pense que cela résoudra le problème dans ton outil.

Doc de jsDoc : http://usejsdoc.org/
Comprendre le typage en JavaScript : https://blog.lesieur.name/les-types-en-javascript-pour-tout-savoir/