JsDoc：我如何记录对象可以具有arbritrary（未知）属性但具有特定类型？ [英] JsDoc: How do I document that an object can have arbritrary (unknown) properties but with a particular type?

问题描述

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

This is a similar to question 30360391. I want to express that the parameter of a function is a plain JS object that can have arbitrary properties (with unknown) names but all properties are objects themselves with fixed properties.

一个例子：函数就像这样

An example: The function is just like this

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

和典型的 desc 看起来像

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 。作为伪代码，它将类似于

I still need a typedef for Descriptor that basically express that Descriptor is an object with arbitrary properties but all of type DescriptorEntry. As pseudo-code it would be something like

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

当然，星号 * 作为任何属性的通配符是无效的Jsdoc语法。但是我该怎么做呢？

Of course, the asterisk * as a wildcard for "any property" is invalid Jsdoc syntax. But how do I do it correctly?

推荐答案

Per http://usejsdoc.org/tags-type.html ，从JSDoc 3.2开始，JSDoc完全支持Google Closure Compiler类型表达式。 http://usejsdoc.org/tags-type.html#中描述了一种此类格式。 jsdoc-types ：

Per http://usejsdoc.org/tags-type.html , as of JSDoc 3.2, JSDoc has had full support of Google Closure Compiler type expressions. One such format is described at http://usejsdoc.org/tags-type.html#jsdoc-types :

{Object.<string, number>}

所以在你的情况下，你应该可以这样做：

So in your case, you should be able to do:

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

或只是：

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

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

You could even replace string in the above examples with its own type, if you wanted to have a special type called DescriptorName or such and detailing the allowable string values.

然而，请注意。至少在我的情况下，虽然JSDoc没有拒绝后一种格式，至少使用默认模板，它只是将它显示为对象而没有任何特殊细节。但是，第一种格式正确显示。

One note, however. In my case at least, while JSDoc is not rejecting the latter format, at least with the default template, it is only showing it as an "Object" without any special details. The first format is shown correctly, however.

这篇关于JsDoc：我如何记录对象可以具有arbritrary（未知）属性但具有特定类型？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！