JSDoc ссылки на функцию обратного вызова

Question

Я решил использовать JSDoc для документирования проекта, над которым я работаю. При чтении руководства по использованию и вопросов здесь я все еще чувствую, что я не хватать некоторых из основных понятий JSDoc и я иллюстрировал свою некомпетентность в следующем примере: http://jsfiddle.net/zsbtykpv/

/** 
* @module testModule 
*/ 

/** 
* @constructor 
*/ 
var Test = function() { 
    /** 
    * @callback myCallback 
    * @param {Object} data An object that contains important data. 
    */ 

    /** 
    * A method that does something async 
    * @param {myCallback} cb a callback function 
    * @return {boolean} always returns true 
    */ 
    this.method = function(cb) { 
     doSomethingAsync(function(data) { 
      cb(data); 
     }); 
     return true; 
    } 

} 

module.exports = Test; 

Здесь я определил модуль, обозначенный конструктор и задокументировал метод, который выполняет обратный вызов как один из его «параметров». Звучит довольно просто и, как представляется, соответствует рекомендациям, приведенным в руководстве по использованию http://usejsdoc.org/.

Но по какой-то причине, кроме моего понимания (и это, вероятно, основная концепция, которую я не получаю), она показывает обратный вызов myCallback как член testModule вместо класса Test. Должен ли он по умолчанию быть членом класса, а не модуля? Это также мешает JSDoc сделать ссылку на определение обратного вызова, что не очень весело.

Теперь я понимаю, что если бы я писал:

/** 
* @callback module:testModule~Test~myCallback 
* @param {Object} data An object that contains important data. 
*/ 

/** 
* A method that does something async 
* @param {module:testModule~Test~myCallback} cb a callback function 
* @return {boolean} always returns true 
*/ 

Я хотел бы получить свое желаемое поведение. Но это, кажется, очень неуклюжий способ делать что-то, а сгенерированные ссылки далеки от хороших.

Извините за длинный раскачки и заранее спасибо за вашу помощь в моей документации усилий :)

Answer 1

Я встречал много с той же проблемой. Если вы хотите хорошо смотрящиеся ссылки, вы всегда можете добавить {@link} в описании и просто использовать каноническое имя в @type, как это:

/** 
* @callback module:testModule~Test~myCallback 
* @param {Object} data An object that contains important data. 
*/ 

/** 
* @param {myCallback} cb {@link module:testModule~Test~myCallback|myCallback}: a callback function 
* @return {boolean} always returns true 
*/ 

Я понимаю, что это немного больше расстраивает типа, но документы myCallback как член класса, а не модуль, и ссылка выглядит красиво.

Если вам действительно нужна ссылка в @type, и вам все равно, как она документирует обратный вызов, вы также можете сделать это, что немного меньше подробностей (и то, что я решил сделать для своего проекта):

/** 
* @callback myCallback 
* @param {Object} data An object that contains important data. 
*/ 

/** 
* @param {module:testModule~myCallback} cb a callback function 
* @return {boolean} always returns true 
*/ 

это будет правильно установить связь с myCallback и документировать его в качестве члена модуля.