JsDoc:我如何记录一个对象可以具有arbitrary(未知）属性，但具有特定类型

JsDoc: How do I document that an object can have arbritrary (unknown) properties but with a particular type?

本文关键字：未知 arbitrary 类型 属性 何记录 JsDoc 一个对象 记录      更新时间：2023-09-26

这与问题30360391类似。我想表达的是，函数的参数是一个普通的JS对象，它可以具有任意的属性（具有未知的）名称，但所有属性本身都是具有固定属性的对象。

举个例子：这个功能就像这个

/**
 * @param {Descriptor} desc
 */
function foo( desc ) {
  // ...
}

典型的CCD_ 1看起来像

desc = {
  unknownEntity1: {
    priority: 5;
    writable: false;
  },
  unknownEntity2: {
    priority: 42;
    writable: true;
  },
  unknownEntity3: {
    priority: 9;
    writable: false;
  }
}

我已经有了

/**
 * @typedef {Object} DescriptorEntry
 * @property {number} priority - The priority of the entity
 * @property {boolean} writable - True, if the entity can be modified
 */

我仍然需要Descriptor的typedef，它基本上表示Descriptor是一个具有任意属性但都是DescriptorEntry类型的对象。作为伪代码，它将类似于

/**
 * @typedef {Object} Descriptor
 * @property {DescriptorEntry} *
 */

当然，星号*作为"任意属性"的通配符是无效的Jsdoc语法。但是我该如何正确地做呢？

Perhttps://jsdoc.app/tags-type.html，从JSDoc 3.2开始，JSDoc已经完全支持Google闭包编译器类型表达式。一种这样的格式在https://jsdoc.app/tags-type.html#jsdoc-类型：

{Object.<string, number>}

所以在你的情况下，你应该能够做到：

/**
 * @typedef {Object.<string, DescriptorEntry>} Descriptor
 */

或者只是：

/**
 * @typedef {{string, DescriptorEntry}} Descriptor
 */

如果您想要一个名为DescriptorName或类似的特殊类型并详细说明允许的字符串值，您甚至可以用自己的类型替换上面示例中的string。

然而，有一点值得注意。至少在我的情况下，虽然JSDoc并没有拒绝后一种格式，至少在默认模板中是这样，但它只是将其显示为"；对象"；没有任何特别的细节。然而，第一种格式显示正确。

这些是PropertyDescriptor和PropertyDescriptorMap的Typescript接口。（它们也被PhpStorm 2020用于代码完成）：TypeScript/lib/lib.es5.d.ts

interface PropertyDescriptor {
    configurable?: boolean;
    enumerable?: boolean;
    value?: any;
    writable?: boolean;
    get?(): any;
    set?(v: any): void;
}
interface PropertyDescriptorMap {
    [s: string]: PropertyDescriptor;
}

您可以将它们直接用作desc0，也可以重新定义两者：

/**
 * @typedef {Object} PropertyDescriptor
 * @property {function(v: *): void} [set]             - Set [name](v){...}      'accessor descriptor' only
 * @property {function(): *}        [get]             - Get [name](){...}       'accessor descriptor' only
 * @property {undefined|*}          [value]           - Value (primitive|func)  valid in 'data descriptor' only
 * @property {undefined|boolean}    [writable]        - Writable                valid in 'data descriptor' only
 * @property {undefined|boolean}    [configurable]    - Configurable            valid in 'data && accessor - descriptor'
 * @property {undefined|boolean}    [enumerable]      - Enumerable              valid in 'data && accessor - descriptor'
 */
/**
 * @typedef {Object<string,PropertyDescriptor>} PropertyDescriptorMap
 */
/**
 *  @type {PropertyDescriptor} myDescriptor
 */
let myDescriptor = {
    configurable: true,
    enumerable: true,
    // value: {},
    // writable: true,
    get myGet(){},
    set myGet(v){}
};
相关文章：