JSDoc - 如何使用通用键名记录对象？ [英] JSDoc - How to document object with generic key names?

问题描述

我已经在堆栈溢出但被告知我的问题应该放在这里。

I already asked this question on Stack Overflow but was told that my question should rather be posted here.

我需要使用JSDoc记录一个ES6类，它接收一个具有键名称的属性的对象作为人的名字，所以键名几乎可以是任何字符串，没有预定义。所以对象的结构应该如下：

I need to document an ES6 class with JSDoc that takes in an object that has properties that has the key names as names of people so the key names can be pretty much any string, nothing predefined. So the structure of the object should be like the following:

{
    "Name of person": {
        "age": 31,
        "hobby": "Tennis"
    },
    "Name of another person": {
        "age": 29,
        "hobby": "Running"
    }
}

所以名字每个人都是一个关键，但它可以是任何东西，它没有预定义。一个我想要记录的例子：

So the name of each person is a key but it can be anything at all, it's not predefined. An example of what I'm trying to document:

class ExampleClass {
    /**
     * Creates an instance of ExampleClass
     * @param {Object} peopleObj            - Contains information about people.
     * @param {String} peopleObj.name       - The name of the person. <----- how should this be documented?
     * @param {Number} peopleObj.name.age   - The age of the person.
     * @param {String} peopleObj.name.hobby - The hobby of the person.
     * @memberof ExampleClass
     */
    constructor(peopleObj) {
        // Do stuff
    }
}

我觉得如果我把peopleObj.name，这意味着键应该是名称，而不是你喜欢的任何名称。那么如何记录这个，让用户知道他可以插入他喜欢的任何名字？

I feel like if I put "peopleObj.name" it implies that the key should be "name" but not any name you like. So how do I document this with letting the user know that he can insert any name he likes there?

推荐答案

你所描述的包含在 @type JSDoc文档中。

What you are describing is covered in the @type JSDoc documentation.

对象应该记录如下：

/**
 * @typedef Person
 * @type {Object}
 * @property {number} age - the person's age
 * @property {string} hobby - the person's hobby
 */

/** 
 * ExampleClass
 */
class ExampleClass {

    /**
     * Creates a dictionary of people
     * @param {Object.<string, Person>} peopleObj - an object with names as keys and Person objects as values. 
     * @memberof ExampleClass
     */
     constructor(peopleObj) {}
}

这篇关于JSDoc - 如何使用通用键名记录对象？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！