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

问题

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 ) {
  // ...
}

and a typical desc looks like

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

I already have

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

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} *
 */

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

回答1:

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
 */

or just:

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

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.

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.

来源：https://stackoverflow.com/questions/38702398/jsdoc-how-do-i-document-that-an-object-can-have-arbritrary-unknown-properties

标签

javascript

documentation

jsdoc

jsdoc3