Last active
September 6, 2023 04:27
-
-
Save ritch/9606670 to your computer and use it in GitHub Desktop.
What is the best way to document complex / dynamic objects as arguments to a function?
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/** | |
* Below are several examples of methods that are difficult to clearly annotate with JSDoc annotations. | |
*/ | |
/** | |
* @param {Object} people An index of people keyed by a person's name | |
* @returns {Object} map An index of zipcodes keyed by a person's name | |
*/ | |
function find(people) { | |
return Object.keys(people).reduce({}, function(prev, cur) { | |
prev[cur] = zipFor(cur); | |
return prev; | |
}); | |
} | |
/** | |
* @param {Object} options The options to set | |
*/ | |
function configure(options) { | |
this.options = options; | |
} | |
/** | |
* @param {Object} options The options to set | |
*/ | |
function configure(options) { | |
this.options = options; | |
} | |
/** | |
* @param {Object} options The options to set | |
* @param {Object} options.server The server options | |
* @param {String} options.server.host The server host | |
* @param {String|Number} options.server.port The server port | |
* @param {Array} options.remoteHosts An array of server options | |
*/ | |
function betterConfigure(options) { | |
this.options = options; | |
} | |
/** | |
* The issue: | |
* | |
* - the documentation above is not clear and sometimes incomplete | |
* - an example would help, but would not be explicit | |
* - it is difficult to describe objects within arrays | |
*/ |
I am working with following:
/** * @typedef {{ * firstName: string, * age: number * }} Person * * @param {{ * [key: keyof Person]: Person * }} p */
Oh, thank you! I was trying to document a hybrid object (which has both static and dynamic properties) for my project and after observing <key,value> example and your example, I finally managed to achieve something like this:
/**@typedef {{
* [jobID:number]: Job,
* jobCount: number
* }} JobDatabase
*/
Why is it not working for me?
An index signature parameter type cannot be a literal type or generic type. Consider using a mapped object type instead.ts(1337)
/**
* @typedef {{
* firstName: string,
* age: number
* }} PersonX
*
*/
/**
* @param {{
* [key: keyof PersonX]: PersonX
* }} px
*/
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
I am working with following: