JSDoc中文文档(@use JSDoc)

JSDoc @variation 标签

目录

语法

@variation <variationNumber>

概述

有时,你的代码可能包括多个同langname的标识符。 例如,你可能有两个全局类,并且顶级的命名空间叫做Widget。 在这些情况下, "{@link Widget}" 或者 "@memberof Widget" 是什么意思呢?全局命名空间,还是全局类?

@variatio将用于JSDoc区分相同longname的不同标识符。例如,如果"@variation 2"被添加到JSDoc注释块中的Widget类,"{@link Widget(2)}"将指向这个类,"{@link Widget}"将指向命名空间。此外,当你使用@alias@name标签指定标识符的时候,还可以包括variatio (例如,"@alias Widget(2)")。

您可以给@variation标签提供任何值,只要值和longname组合导致全球唯一的longname的版本。最佳做法是,用一个可预测的模式进行选择值,这将使它更容易为您记录您的代码。

示例

下面的示例使用@variation标签来区分Widget类和Widget命名空间。

示例: 使用@variation标签
/**
 * The Widget namespace.
 * @namespace Widget
 */

// you can also use '@class Widget(2)' and omit the @variation tag
/**
 * The Widget class. Defaults to the properties in {@link Widget.properties}.
 * @class
 * @variation 2
 * @param {Object} props - Name-value pairs to add to the widget.
 */
function Widget(props) {}

/**
 * Properties added by default to a new {@link Widget(2)} instance.
 */
Widget.properties = {
    /**
     * Indicates whether the widget is shiny.
     */
    shiny: true,
    /**
     * Indicates whether the widget is metallic.
     */
    metallic: true
};