@module¶

.. @module::¶

语法

@module [[{<type>}] <moduleName>]

概述

在JSDoc 3.3.0及更高版本中, ``<moduleName>``可能包含``module: ``前缀. 在以前的版本中, 您必须省略此前缀.

注意

If you provide a type, you must also provide a name.

@module标记将当前文件标记为自己的模块. 除非另有说明, 否则假定文件中的所有符号都是模块的成员.

Link to a module (e.g. within a [@link]link or [@see]see tag) using “module:moduleName”. For example, “@module foo/bar” can be linked to using “{@link module:foo/bar}”.

如果未提供模块名称, 则它是从模块的路径和文件名派生的. 例如, 假设我有一个位于``src``目录下的文件``test.js``, 它包含块注释``/ ** @module */``. 以下是运行JSDoc的一些场景以及test.js的结果模块名称:

Derived module names if none is provided.¶

# from src/
jsdoc ./test.js   # module name 'test'

# from src's parent directory:
jsdoc src/test.js # module name 'src/test'
jsdoc -r src/     # module name 'test'

示例

以下示例显示了用于模块中符号的名称路径. 第一个符号是模块私有或“内部”变量 - 它只能在模块中访问. 第二个符号是由模块导出的静态函数.

Basic @module use¶

/** @module myModule */

/** will be module:myModule~foo */
var foo = 1;

/** will be module:myModule.bar */
var bar = function() {};

当导出的符号被定义为``module.exports``, ``exports``或``this``的成员时, JSDoc推断符号是模块的静态成员.

在下面的示例中, Book类被记录为静态成员“module: bookshelf.Book”, 其中包含一个实例成员“module: bookshelf.Book＃title”.

Defining exported symbols as a member of ‘this’¶

/** @module bookshelf */
/** @class */
this.Book = function (title) {
    /** The title. */
    this.title = title;
};

在以下示例中, 这两个函数的名称路径为“module: color/ mixer.blend”和“module: color/ mixer.darken”.

Defining exported symbols as a member of ‘module.exports’ or ‘exports’¶

/** @module color/mixer */
module.exports = {
    /** Blend two colours together. */
    blend: function (color1, color2) {}
};
/** Darkens a color. */
exports.darken = function (color, shade) {};

有关更多示例, 请参阅`记录JavaScript模块<howto-commonjs-modules.html>`__.