Как документировать метод с несколькими псевдонимами? - PullRequest
Новая
       72

Как документировать метод с несколькими псевдонимами?

0 голосов
/ 02 мая 2018

Я пытаюсь задокументировать метод getName () следующего конструктора Person:

Код Javascript: 

/**
 * Creates a person instance.
 * @param {string} name The person's full name.
 * @constructor
 */
function Person( name ) {

    /**
     * Returns the person's full name.
     * @return {string} The current person's full name.
     */
    function getName() {
        return name;
    }

    this.getName = getName;
    this.getN = getName;
    this.getFullName = getName;
}

Как видите, метод getName () имеет два псевдонима ( getN () и getFullName () ), поэтому очевидный тег использовать это тег @ alias , но, к сожалению, у него есть две основные проблемы:

1 - Он сообщает JSDoc переименовать метод.

2 - Нельзя использовать для нескольких псевдонимов .

Есть ли какой-нибудь официальный способ документировать подобные методы?

1 Ответ

0 голосов
/ 02 мая 2018

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

Тег @ займ позволяет добавлять документацию для другого символа в ваша документация.

Этот тег будет полезен, если у вас есть более чем один способ ссылки на функция , но вы не хотели дублировать ту же документацию в два места.

Итак, getName () должен быть задокументирован следующим образом:

Javascript код: 

/**
 * Creates a person instance.
 * @param {string} name The person's full name.
 * @constructor
 * @borrows Person#getName as Person#getN
 * @borrows Person#getName as Person#getFullName
 */
function Person( name ) {

    /**
     * Returns the person's full name.
     * @return {string} The current person's full name.
     * @instance
     * @memberof Person
     */
    function getName() {
        return name;
    }

    this.getName = getName;
    this.getN = getName;
    this.getFullName = getName;
}

JSDoc результат:

Result

...