¿Hay alguna manera de evitar el uso de jsdoc "@method" Anotación

Question

No soy un gran fan de la documentación generada personalmente (yo soy más de un "leer la fuente Lucas" un poco el individuo), pero puedo ver cómo tal documentación podría ser útil para otros. Ahora, normalmente la generación de la documentación no me impacto, excepto por una cosa: @method.

La mayoría de las anotaciones jsdoc (por ejemplo @param.) Siguen siendo perfectamente útil para alguien que está leyendo la fuente, pero @method es 100% redundante:

/* 
* @param num number to add five to 
* @method addFive 
*/ 
function addFive(num) { ... 

Así que, realmente me gustaría evitar tener cientos de líneas @method abarrotando nuestro código. Sin embargo, mi compañero de trabajo cree que @method es necesario para los generadores jsdoc (que está usando el YUI uno) para poder generar las listas de métodos de clases.

Entonces, mi pregunta (a los expertos de JSDoc) es: ¿hay alguna manera de generar documentación útil (es decir, con los métodos de una clase enumerada) sin @method? O si realmente se requiere @method, ¿hay algún generador de JSDoc que pueda inferir el nombre del método del nombre de la función, de modo que pueda salirse con @method en lugar de @method addFive?

P.S. Si hay un "lo estás haciendo mal" respuesta de tipo que no responde directamente a la pregunta, pero sugiere una forma de evitar el problema por completo, me encantaría escucharlo; Ciertamente no soy un experto en JSDoc.

Answer 1

Su compañero de trabajo no es estrictamente correcto.

La @method es una extensión JSDoc3 que es un sinónimo de @function, que es defined here.

Como los documentos describen, solo necesita usar @function a force JSDoc para reconocer una variable como una función. Un ejemplo de esto sería:

/** 
* @function 
*/ 
var func = functionGenerator.generate(); 

Desde un punto de vista objetivo, que querría hacer lo mismo cada vez que se asigna un objeto de función a un miembro objeto de una manera no evidente (por 'no evidente' , me refiero en términos de análisis estático, es decir, si usted no está utilizando una expresión de función).

Por lo tanto, algo así como

var ageGetter = function() { 
    console.log("A lady never tells"); 
} 

var Person = { 

    name: "Gertrude", 

    getAge: ageGetter 

    getName: function() { 
    return this.name; 
    } 
} 

pueda requerir el uso explícito de @method o @function para getAge, pero no para getName.

Punto final: no es necesario que incluya explícitamente el nombre @method a menos que eso también sea imposible de inferir (en ese momento, probablemente esté haciendo una instancia bastante funky, por lo que probablemente no haya podido confiar en autodoc generación mucho de todos modos).

Answer 2

Podría estar equivocado aquí, pero debido a la multitud de formas de definir cosas en JavaScript, necesita @method para ciertas definiciones.

// JSDoc will recognize this as an object member 
var obj = { 
    mymethod: function() {} 
}; 

// There is no way for JSDoc to tell where my method is going to end up 
var mymethod = function() {}; 
obj.mymethod = mymethod;