Skip to content

Instantly share code, notes, and snippets.

@mungurs
Forked from ritch/ex.js
Created October 9, 2018 06:56
Show Gist options
  • Save mungurs/d59d17d235457451ff465cf4edfe0498 to your computer and use it in GitHub Desktop.
Save mungurs/d59d17d235457451ff465cf4edfe0498 to your computer and use it in GitHub Desktop.
What is the best way to document complex / dynamic objects as arguments to a function?
/**
* 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
*/
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment