style - Documentar los efectos secundarios de los métodos javascript.

title js

Question

Intento mejorar la documentación de mi código javascript y sigo las pautas de JSDoc http://usejsdoc.org/ .

No encuentro cómo documentar un efecto secundario intencional. Por ejemplo el siguiente método:

/**
  * @description
  *   Paints the object red.
  * @return
*/
Painter.paintItRed = function(someObj){
    someObj.color = "red";
};

¿Cómo se documenta el hecho de que el método actúa directamente sobre el objeto pasado? Un ejemplo diferente:

/**
  * @description
  *   If the user has not setUp a config, show config Modal.
  * @return
*/
User.checkConfig = function(user){
    if(!user.config.valid){
       showConfigModal();
    }
};

Estos son ejemplos artificiales y probables "olores de código", pero ese es otro problema. Estoy viendo algunas de las mejores prácticas sobre cómo documentar este tipo de comportamiento (para bien o para mal). Algo tal vez mejor que //IMPORTANT!! This method is dangerous! //IMPORTANT!! This method is dangerous!

Answer 1

No hay una forma estandarizada de hacer esto. Al menos no en JavaDoc , que, para ser justos, es lo que JSDoc está imitando. Hay un problema para agregarlo a JSDoc, por cierto, que en realidad hace referencia a esta pregunta.

Si realmente desea documentar esto, puede agregar una etiqueta personalizada, como puede hacerlo para JavaDoc . Podría usar eso para agregar, por ejemplo, una etiqueta @affects . Podría ser utilizado de la siguiente manera.

/**
 * @description
 *   Paints the object red.
 * @param someObj
 *   The object to be painted.
 * @affects
 *   someObj.color
 */
Painter.paintItRed = function(someObj) {
    someObj.color = ''red'';
};

Definir una etiqueta personalizada en JSDoc no es difícil , también vea esta pregunta relacionada .