如何在 JSDoc 中记录有关对象的 属性 的更复杂信息？
How to document more complex informations about a property of an object in JSDoc?
请看下面的代码。所以我有一个对象，我想用 jsdoc 记录它的属性，所以我使用 jsdoc 的 @property tag 来记录这个 myObject 对象的那些属性。但是，我也想记录更复杂的信息，比如一些代码示例，而不仅仅是简单的名称、类型和描述。
但是在documentation of this @property tag中，他们说我们只能添加那些简单的名称或描述信息，不能添加更复杂的东西（他们说：“它不允许你提供@examples 或类似的复杂信息...").
/**
* An object with some simple properties
* @type {Object}
* @property {String} firstProperty This is the first property with a string value
* @property {Number} secondProperty This is the second property with a number value
*/
const myObject = {
firstProperty: 'This is the first property',
secondProperty: 33,
}
从那里你可能已经知道我的意思了。我想问一下是否有一种方法可以仅使用 JSDoc 添加示例代码或有关对象属性的更复杂信息。非常感谢！
如果他们说“你不能”。你真的不能。 ♂️
首先，我应该注意到 JsDoc 非常灵活，更重要的是，它会尝试通过解析您的代码并提取其中的内容来填充它需要的任何未明确标记的细节（如描述或数据类型）需要。
但这并不意味着您只能记录 JsDoc 可以在您的代码中找到的内容。
事实上，如果您确保 JsDoc 具有生成文档所需的一切，您可以为代码中未明确存在的许多内容创建文档。
至少，每个“可记录”的对象都必须有一个名称，并且可能与另一个对象有关系。
大概，您的对象记录在一个模块中，因此您始终可以将示例添加到顶级 doclet 的 @module 部分，例如：
/**
* Encapsulates the concept of a Widget.
*
* @example
*
* // assuming we have previously instantiated a disp:Display
*
* var opts = { ... };
*
* var w = new Widget(opts);
*
* w.displayOn(disp);
*
* @module
*/
或者，您可以将您的文档添加到一个不存在的命名项目中，如：
/**
* Example of how to use the Object properties.
*
* @name ObjectPropertyExample
* @memberof MyObject
*
* @example
* ...
*/
在 jsdoc 中，您提供 @name 的任何内容都将包含在您的文档中。
如果添加 @memberof 标签，您可以将新实体分配给另一个已定义的对象，甚至可以将其分配给您动态创建的对象。
如果您不添加 @memberof 标签，该项目将与抽象的“全局”对象相关联。
以上示例将在您的文档中创建对 MyObject~ObjectPropertyExample 的引用。
请看下面的代码。所以我有一个对象，我想用 jsdoc 记录它的属性，所以我使用 jsdoc 的 @property tag 来记录这个 myObject 对象的那些属性。但是，我也想记录更复杂的信息，比如一些代码示例，而不仅仅是简单的名称、类型和描述。
但是在documentation of this @property tag中，他们说我们只能添加那些简单的名称或描述信息，不能添加更复杂的东西（他们说：“它不允许你提供@examples 或类似的复杂信息...").
/**
* An object with some simple properties
* @type {Object}
* @property {String} firstProperty This is the first property with a string value
* @property {Number} secondProperty This is the second property with a number value
*/
const myObject = {
firstProperty: 'This is the first property',
secondProperty: 33,
}
从那里你可能已经知道我的意思了。我想问一下是否有一种方法可以仅使用 JSDoc 添加示例代码或有关对象属性的更复杂信息。非常感谢！
如果他们说“你不能”。你真的不能。 ♂️
首先，我应该注意到 JsDoc 非常灵活，更重要的是，它会尝试通过解析您的代码并提取其中的内容来填充它需要的任何未明确标记的细节（如描述或数据类型）需要。
但这并不意味着您只能记录 JsDoc 可以在您的代码中找到的内容。
事实上，如果您确保 JsDoc 具有生成文档所需的一切，您可以为代码中未明确存在的许多内容创建文档。
至少，每个“可记录”的对象都必须有一个名称，并且可能与另一个对象有关系。
大概，您的对象记录在一个模块中，因此您始终可以将示例添加到顶级 doclet 的 @module 部分，例如：
/**
* Encapsulates the concept of a Widget.
*
* @example
*
* // assuming we have previously instantiated a disp:Display
*
* var opts = { ... };
*
* var w = new Widget(opts);
*
* w.displayOn(disp);
*
* @module
*/
或者，您可以将您的文档添加到一个不存在的命名项目中，如：
/**
* Example of how to use the Object properties.
*
* @name ObjectPropertyExample
* @memberof MyObject
*
* @example
* ...
*/
在 jsdoc 中，您提供 @name 的任何内容都将包含在您的文档中。
如果添加 @memberof 标签，您可以将新实体分配给另一个已定义的对象，甚至可以将其分配给您动态创建的对象。
如果您不添加 @memberof 标签，该项目将与抽象的“全局”对象相关联。
以上示例将在您的文档中创建对 MyObject~ObjectPropertyExample 的引用。