当我一个一个添加时，使用 JSDoc 记录数据对象成员的正确方法是什么？

Question

我有一个只包含一些静态项的 JS 数据对象。我不会在 { } 中一次性声明所有内容；我从一个空对象开始，一次添加一个项目。例如：

var ScapeStuff = {};

// some generic stuff
ScapeStuff.generic = new SomeClass(...);

// water
ScapeStuff.water = new SomeClass(...);

// dirt of various moisture levels
var dry = someValue
var wet = anotherValue
// interpolate moisture...
ScapeStuff.dirt0 = new SomeClass(dry);
ScapeStuff.dirt1 = new SomeClass((dry + dry + wet) / 3);
ScapeStuff.dirt2 = new SomeClass((dry + wet + wet) / 3);
ScapeStuff.dirt3 = new SomeClass(wet);

// some other types of stuff..

// finally, export this data object
module.exports = ScapeStuff;

我想用 JSDoc 记录我的 ScapeStuff 数据对象，并用描述该内容的 JSDoc 注释替换像 // water 这样的注释行。

我可以在 ScapeStuff = {} 上方添加一个巨大的 JSDoc 注释，然后使用 @member 为每个属性项目编写描述，但文件可能会很长，所以我真正想要的是在属性.

之前为源中的每个属性添加 JSDoc 注释

在这种情况下，使用内联 JSDoc 注释的正确方法是什么？

Answer 1

自己找到了答案。

首先，我将 ScapeStuff 容器记录为 @namespace，如下所示：

/**
 * Stuff (that is, THREE.Material) that things in scapes can be made out of.
 * @namespace
 */
var ScapeStuff = {};

现在我可以使用 @memberof 告诉 JSDoc 我添加到最初为空的对象的每个新事物都是 ScapeStuff 命名空间的成员。

/** some generic stuff
  * @memberof ScapeStuff */
ScapeStuff.generic = new SomeClass(...);

/** water
  * @memberof ScapeStuff */
ScapeStuff.water = new SomeClass(...);

所以，我如愿以偿——我可以记录成员在源代码中出现的位置，并且仍然让 JSDoc 将它们显示为在父对象中。耶我！

当我一个一个添加时，使用 JSDoc 记录数据对象成员的正确方法是什么？

The right way to use JSDoc to document a data object's members, when I add them one by one?

javascript

jsdoc

jsdoc3