[英]How do I document an object with JSDoc?
What's the best way to document the source code of a simple JavaScript object (and its export) using JSDoc?使用 JSDoc 记录简单 JavaScript 对象(及其导出)的源代码的最佳方法是什么?
For example, I want to document the following object:例如,我想记录以下对象:
/** how do I JSDocument object baseAdder? */
const baseAdder = {
/** how do I JSDocument property base? */
base: 1,
/**
* Add a number to base
* @param {number} a the number to be added to base
* @returns {number} the sum of the number plus base
*/
f: function(a) {
return this.base + a;
}
};
/** how do I JSDocument this export? Should I? */
module.exports = baseAdder;
A basic JS Doc documentation is like.一个基本的 JS Doc 文档就像。
/*
* {Object} baseAdder - Base Adder object
* {Number} baseAdder.base - Base value
* {function} baseAdder.f - A function f on the Base Adder
*/
const baseAdder = {
base: 1,
/**
* Add a number to base
* @param {Number} - a the number to be added to base
* @returns {Number} - the sum of the number plus base
*/
f: function(a) {
return this.base + a;
}
};
/**
* A module of base adder!
* @module baseAdder
*/
module.exports = baseAdder;
For more reference follow the official documentation - http://usejsdoc.org/index.html有关更多参考,请遵循官方文档 - http://usejsdoc.org/index.html
In most cases, your CommonJS or Node.js module should include a standalone JSDoc comment that contains a @module tag.在大多数情况下,您的 CommonJS 或 Node.js 模块应该包含一个包含 @module 标签的独立 JSDoc 注释。 The @module tag's value should be the module identifier that's passed to the require() function. @module 标签的值应该是传递给 require() 函数的模块标识符。 For example, if users load the module by calling require('my/shirt'), your JSDoc comment would contain the tag @module my/shirt.例如,如果用户通过调用 require('my/shirt') 加载模块,则您的 JSDoc 注释将包含标签 @module my/shirt。
See Documenting JavaScript Modules请参阅记录 JavaScript 模块
A standalone JSDoc comment for that would be:对此的独立 JSDoc 评论是:
/** @module so/answer */
Meaning that we would require your module as follow:这意味着我们需要您的模块如下:
const adder = require('so/answer');
Your baseAdder
object is actually a namespace (see @namespace
) with two static members: a number and a function.您的baseAdder
对象实际上是一个具有两个静态成员的命名空间(请参阅@namespace
):一个数字和一个函数。
/** @module so/answer */
/** @namespace */
const baseAdder = {
/**
* @type {number}
* @default 1
*/
base: 1,
/**
* @param {number} a the number to be added to base
* @return {number} the sum of the number plus base
*/
f: function(a) {
return this.base + a;
}
};
module.exports = baseAdder;
Unless explicitly documented otherwise, all symbols within a module are members of that module.除非另有明确说明,模块中的所有符号都是该模块的成员。 So your namespace now belongs to that module.所以你的命名空间现在属于那个模块。
Warning: It is a common mistake to use {Number}
instead of {number}
.警告:使用{Number}
而不是{number}
是一个常见的错误。 These are two different type expressions.这是两种不同类型的表达式。 The first refers to a number object eg new Number(42)
and the second refers to a literal number eg 42
.第一个引用数字对象,例如new Number(42)
,第二个引用文字数字,例如42
。
In practice, people looking at your documentation are likely to assume a literal number either way but this distinction becomes important if you use a static type checker based on JSDoc.在实践中,查看您的文档的人可能会以任何一种方式假设一个字面数字,但如果您使用基于 JSDoc 的静态类型检查器,这种区别就变得很重要。
See also my JSDoc Cheat Sheet if you're interested.如果您有兴趣,另请参阅我的JSDoc 备忘单。
What the doc looks like when generated via JSDoc通过 JSDoc 生成的文档是什么样的
Index:指数:
Let's see your module:让我们看看你的模块:
Let's see your namespace:让我们看看你的命名空间:
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.