jsdoc: Как мне получить параметры метода экземпляра?

Question

Я пытаюсь документировать старый код с JSDoc3, и я застреваю, пытаясь заставить его включить в документацию параметры к методам экземпляра - или вообще показать что-либо как свойство экземпляра. Я подозреваю, что проблема в том, что код не соответствует ожидаемой идиоме для фальсификации классов в javascript, но я хочу, чтобы все было задокументировано, прежде чем начинать переписывать что-либо. Я пытался сделать небольшой пример проблемы, со структурой фактического кода:

/** 
* Global function 
* @param {Object} v Stuff that they're trying to avoid making global 
* @return {Object} Updated v 
*/ 
jsdoc_test = function(v) { 
    /** 
    * Some stuff is defined in this namespace 
    * @namespace space 
    */ 
    var space = {}; 
    /** 
    * Something that acts like a class 
    * @name space.someclass 
    * @memberOf space 
    * @constructor 
    * @type {function} 
    * @param {any} y blah blah 
    * @return {Object} The constructed object 
    */ 
    space.someclass = function(w) { 
     var obj = { 
      source: w,  // might need this again 
      derived: foo(w), // what we usually need 
      etc:  "etc"  // and so on 
     }; 
     /** 
     * This should be a member function, but it appears as a static property 
     * @name space.someclass.methodA 
     * @memberOf space.someclass 
     * @type {function} 
     * @instance 
     * @param {any} x Parameters do not appear in documentation 
     * @return {Object} this 
     */ 
     obj.methodA = function(x) { 
      bar(x); // or whatever methodA does 
      return this; 
     } 
     /** 
     * This should be a member function, but it doesn't show up at all 
     * @name space.someclass.methodB 
     * @memberOf space.someclass# 
     * @type {function} 
     * @param {any} y Parameters do not appear in documentation 
     * @return {Object} this 
     */ 
     obj.methodB = function(y) { 
      baz(y); // or whatever methodB does 
      return this; 
     } 
     return obj; 
     /** 
     * This should be a member function, but it doesn't show up at all 
     * @name space.someclass.methodC 
     * @memberOf space.someclass.prototype 
     * @type {function} 
     * @param {any} z Parameters do not appear in documentation 
     * @return {Object} this 
     */ 
     obj.methodC = function(z) { 
      qux(z); // or whatever methodC does 
      return this; 
     } 
     return obj; 
    } 
    // ... 
} 

Я хочу, чтобы все три метода появляется в сгенерированной документации как методы экземпляра. Как это, methodA выглядит как статическое свойство, а methodB и methodC (которые следуют предложения от here) не появляются на всех

Как получить JSDoc3 документировать методы экземпляра, с их параметрами, без переписывания кода?

Answer 1

Похоже, вы используете слишком много тегов для своего кода. Когда вы используете @constructor, вам не нужно @name или @type, так как они покрываются с помощью конструктора.

Итак, у вас есть два варианта, я думаю.

@constructor Использование и удаление резервированного (конфликтующие) теги:

/** 
* Something that acts like a class 
* @constructor space.someclass 
* @memberOf space 
* @param {any} y blah blah 
* @return {Object} The constructed object 
*/ 

Или, если вы не хотите использовать @constructor тег, добавьте соответствующий намекая себя:

/** 
* Something that acts like a class 
* @name space.someclass 
* @memberOf space 
* @kind class 
* @param {any} y blah blah 
* @return {Object} The constructed object 
*/ 

В оба случая, @type является избыточным, поскольку вы документируете класс; тип технически будет полным именем вашей функции (то есть, @type {space.someclass}).

Answer 2

Сочетания @instance, @memberOf & @method должен это сделать:

/** 
* This should now be a member function. 
* @instance 
* @memberOf space.someclass 
* @method methodA 
* @param {*} x Some parameter of any type. 
* @return {Object} this. 
*/