Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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?

like image 916
user2690527 Avatar asked Aug 01 '16 15:08

user2690527


People also ask

How do you document an object in JSDoc?

If a parameter is expected to have a specific property, you can document that property by providing an additional @param tag. For example, if an employee parameter is expected to have name and department properties, you can document it as follows: /** * Assign the project to a list of employees.

What is JSDoc comment?

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating.

Can you use JSDoc with TypeScript?

You can use most JSDoc type syntax and any TypeScript syntax, from the most basic like string to the most advanced, like conditional types.

What is Typedef in JS?

The @typedef tag is useful for documenting custom types, particularly if you wish to refer to them repeatedly. These types can then be used within other tags expecting a type, such as @type or @param. Use the @callback tag to document the type of callback functions.


1 Answers

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.

like image 142
Brett Zamir Avatar answered Oct 20 '22 01:10

Brett Zamir