Juan Felipe Martín
Estoy tratando de documentar mi programa con la sintaxis JSDoc para mí y para las personas que tendrán que ver mi código. También estoy tratando de mejorar mis habilidades.
Para un parámetro del tipo jQuery, estoy un poco desconcertado. Sé que es un objeto, pero es bastante común en mi programa, así que creo que primero debería declarar un typedef para el tipo jQuery y luego usarlo como mi tipo de parámetro. Así que pregunto, ¿sería la forma correcta de hacerlo?
/**
* DOM object referenced by jQuery
* @typedef {jQuery} $jQueryDomObject
*/
/**
* SOAP call that does ...
*
* @param {string} code Some desc ...
* @param {callback} fnctVa Some desc ...
* @param {$jQueryDomObject} $attrib Input field that ...
*/
myfunction = function (code, fnctVa, $attrib) {};
También encontré en SO esta pregunta, algo similar:
¿Cómo puedo hacer que JSDoc marque mi parámetro como un objeto jQuery?
Para un parámetro que es un objeto jQuery, a menudo hago lo siguiente:
@param {jQuery} foo
Y no defina más qué es jQuery. Se sabe lo suficiente. Sin embargo, si lo desea, puede hacerlo con jsdoc 3:
/**
* jQuery object
* @external jQuery
* @see {@link http://api.jquery.com/jQuery/}
*/
/**
* SOAP call that does ...
*
* @param {string} code Some desc ...
* @param {callback} fnctVa Some desc ...
* @param {external:jQuery} $attrib Input field that ...
*/
var myfunction = function (code, fnctVa, $attrib) {};
Juan Felipe Martín
también vi en github/js3doc:
@param {jQuery object} obj The jQuery object you're looking for.
@param {module:jquery} jquery Some desc...
Lo correcto es no hacer una llamada SOAP usando un objeto jQ y separar preocupaciones. Solo digo. Interesante pregunta de todos modos.
– Benjamin Grünbaum
27/11/2013 a las 20:20
Ok, investigaré esto. ¿A quién sugerirías un patrón en su lugar?
– Jean-Philippe Martín
27 de noviembre de 2013 a las 20:23
La separación de preocupaciones es un principio y no un patrón. La idea en este caso (es aplicable a más de GUI) es que su lógica de presentación y lógica de negocios no deben mezclarse así. Algunos patrones de diseño comunes que abordan el problema son el mediador, el observador y el emisor de eventos. Algunos patrones arquitectónicos que abordan el problema son MVC, MVVM y MVP.
– Benjamin Grünbaum
27/11/2013 a las 20:33
Gracias por la sugerencia de arquitectura … está bien, entonces la GUI no habla directamente con los datos y viceversa. Entiendo.
– Jean-Philippe Martín
27/11/2013 a las 20:36
@Jean-PhilippeMartin, he hecho casi lo mismo documentando el código heredado que no tuve que escribir.
– Andy
27 de noviembre de 2013 a las 20:49