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 .