如何记录具有多个别名的方法? [英] How to document a method with multiple aliases?

问题描述

我正在尝试记录以下Person构造函数的 getName()方法:

I'm trying to document the getName() method of The following Person constructor :

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 标记，但不幸的是，它有两个主要问题:

As you can see, the getName() method has two aliases ( getN() and getFullName() ), so the obvious tag to use is the @alias tag, but unfortunately, it has two major problems :

1-它告诉JSDoc 重命名方法.

2-它不能用于多个别名.

有没有正式的方法可以记录这些方法?

Is there any official way to document these kind of methods ?

推荐答案

这个问题的答案听起来有些可笑，但是，实际上，有一种正式的方法别名记录方法，他们称之为

The answer to this question may sound a bit funny but, actually, there is an official way to document method aliases, and they call it @borrows .

@borrows 标记可让您将其他符号的文档添加到 您的文档.

The @borrows tag allows you to add documentation for another symbol to your documentation.

如果您有多种引用方式来引用 功能，但您不想在其中重复相同的文档 两个地方.

This tag would be useful if you had more than one way to reference a function, but you didn't want to duplicate the same documentation in two places.

因此， 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结果:

这篇关于如何记录具有多个别名的方法?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！