Альтернатива @name для документирования свойств `this`

Мне интересно, как документировать свойства this. функции конструктора класса. Например, я пробовал использовать тег @name для именования своего класса, но он не создал документацию для this.foo:

/**
 * @name ClassName
 * @constructor
 */
function noname (){
    /** @type {String} */
    this.foo = "bar";
}

Я могу решить это так:

/**
 * @name ClassName
 * @constructor
 */
function noname (){
    /** 
    * @type {String} 
    * @name ClassName#foo
    */
    this.foo = "bar";
}

или таким образом:

/**
 * @name ClassName
 * @constructor
 */
function noname (){
    /** @lends ClassName# */
    var that = this;

    /** @type {String} */
    that.foo = "bar";
}

Однако ни один из них не является удовлетворительным, потому что это потребует либо изменения большого количества существующего кода, либо добавления всех имен свойств в комментарии jsdoc.

Поскольку @name не работает, есть ли альтернативный тег, который поможет?


javascript jsdoc documentation
person user2192086    schedule 20.03.2013    source источник

Ответы (2)


arrow_upward
2
arrow_downward

Вместо этого попробуйте использовать тег @alias:

/**
 * @alias ClassName
 * @constructor
 */
function noname (){
    /** @type {String} */
    this.foo = "bar";
}

В общем, используйте тег @alias для переименования символа, который существует в вашем коде; используйте тег @name, если вы документируете символ, которого нет в вашем коде (например, метод, созданный во время выполнения).

person Jeff Williams    schedule 04.04.2013

arrow_upward
0
arrow_downward

@name отвязывает докблок от следующего кода.

http://usejsdoc.org/tags-name.html

Предупреждение. Используя тег @name, вы указываете JSDoc игнорировать окружающий код и рассматривать ваш комментарий к документации изолированно. Во многих случаях вместо этого лучше использовать тег @alias.

Таким образом, любые внутренние элементы также должны иметь правильное @name (см. http://usejsdoc.org/about-namepaths.html для правильного синтаксиса).

person Konstantin Pelepelin    schedule 17.12.2014