Given a type definition:
/**
* #typedef {object} Foo
* #property {string} someString
* #property {number} someNumber
*/
is there a way to create another type definition that includes only a subset of the parent's properties? E.g. the effective result would be something like:
/**
* #typedef {object} Bar
* #property {string} someString
*/
but using someString as it was already defined in Foo
I am trying to use jsdoc to document function parameters. A single array (routes) is passed in that contains n objects. Each object has a sequences attribute that takes an array, that again contains n objects with a set of attributes.The function is called like in the following example:
myFunction(
[
{
isClickable: true,
isSelected: false,
popupTitle: 'Route Biel/Bienne >> Freiburg/Fribourg',
popupContent: ['Von: Biel/Bienne', 'Nach: Freiburg/Fribourg'],
sequences: [
{
latLonTo: [46.68848, 7.68974],
latLonFrom: [46.94691, 7.44079],
mot: 'rail',
},
],
},
{
isClickable: true,
isSelected: false,
popupTitle: 'Route Bern >> Freiburg/Fribourg',
popupContent: ['Von: Bern', 'Nach: Freiburg/Fribourg'],
sequences: [
{
uicFrom: 8507150,
uicTo: 8545100,
mot: 'bus',
},
],
}
]
)
My documentation is as follows:
/**
* Load routes based on a given configuration.
* #param {Object[]} routes Routes.
* #param {boolean} routes[].isSelected If true, the route is
* selected initially.
* #param {boolean} routes[].isClickable If true, the route can be
* selected or unselected by click.
* #param {Object[]} routes[].sequences Route sequences.
* #param {number} routes[].sequences[].uicFrom UIC number of start station.
* #param {number} routes[].sequences[].uicTo UIC number of end station.
* #param {array} routes[].sequences[].latLonFrom Lat/Lon coordinate array of start location
* (to be used if uicFrom not provided).
* #param {array} routes[].sequences[].latLonTo Lat/Lon coordinate array of end location
* (to be used if uicTo not provided).
* #param {string} routes[].sequences[].mot Method of transportation.
* Allowed values are "rail", "bus", "tram", "subway", "gondola",
* "funicular" and "ferry"
* #returns {Promise<Feature[]>} Promise resolving OpenLayers features.
*/
The result is not as expected, as demonstrated in the following picture:
As indicated in red in the pictures, the parameters in the multidimentional/nested sequence array is not parsed properly by jsdoc. Before the second brackets the rest of the string is added to the description column instead of the name column. The correct output should be:
Does anyone know how to achieve this? I am also open to other,maybe more correct approaches of using jsdoc.
Thanks a lot for any help
I would use two #typedef annotations:
Route
Sequence
/**
* #typedef {Object} Sequence
* #property {Array<number>} latLonTo
* #property {Array<number>} latLonFrom
* #property {string} mot
*/
/**
* #typedef {Object} Route
* #property isClickable {boolean}
* #property isSelected {boolean}
* #property popupTitle {string}
* #property popupContent {Array<string>}
* #property sequences {Array<Sequence>}
*/
/**
* #param {Array<Route>} routes
*/
const func = routes => 42;
Which produces the following documentation:
I have a function with a huge list of options:
/**
* Show dialog in a blocking manner.
*
* #param {object} opts
* #param {string} opts.msg "Body" of the dialog.
* #param {number} opts.timeout Seconds - floating point values are rounded. (ActiveX imposes this)
* #param {string} opts.title Title of the dialog.
* #param {number} opts.icon Use constants for this. (See docs)
* #param {number} opts.buttons Use constants for this. (See docs)
* #param {number} opts.defaultButton Use constants for this. (See docs)
* #returns {number} Use our constants to check for what the user chose.
*/
const showSync = (opts) => {
...
}
But I also have a non-blocking version of this function obviously takes the same options and returns a Promise. It seems quite dirty to copy/paste the docs, as this will decrease maintainability and likelihood for accidental inconsistency.
So what would be great is something like the following:
/**
* Shows dialog in a non-blocking manner.
*
* #inheritdoc showSync
* #returns {Promise<number>} Use our constants to check for what the user chose.
*/
const show = (opts) => {
...
}
Is this possible somehow?
[UPDATE]
This is not a duplicate of JSDoc for reused Function interface because that question is merely about reusing the same definition, while this one is about reusing but also partly overwriting that definition. And hence, the answer there does not answer the question here.
I think the best way to do that with jsdoc is something like this:
/**
* Options for showing a dialog.
* #typedef {Object} ShowOptions
* #property {string} msg "Body" of the dialog.
* #property {number} timeout Seconds - floating point values are rounded. (ActiveX imposes this)
* #property {string} title Title of the dialog.
* #property {number} icon Use constants for this. (See docs)
* #property {number} buttons Use constants for this. (See docs)
* #property {number} defaultButton Use constants for this. (See docs)
*/
/**
* Show dialog in a blocking manner.
*
* #param {ShowOptions} opts
* #returns {number} Use our constants to check for what the user chose.
*/
const showSync = (opts) => {...}
/**
* Shows dialog in a non-blocking manner.
*
* #param {ShowOptions} opts
* #returns {Promise<number>} Use our constants to check for what the user chose.
*/
const show = (opts) => {...}
You could take it a step further and apply a similar concept to the return value as well:
/**
* Use our constants to check for what the user chose.
* #typedef {number} ShowResult
*/
/**
* Show dialog in a blocking manner.
*
* #param {ShowOptions} opts
* #returns {ShowResult}
*/
const showSync = (opts) => {...}
/**
* Shows dialog in a non-blocking manner.
*
* #param {ShowOptions} opts
* #returns {Promise<ShowResult>}
*/
const show = (opts) => {...}
How can I document possible configuration properties in function argument in JSDOC:
/**
* N level expectimax AI.
*
* #param {object} cfg config
* cfg.minimaxDepth - limit for minimax search
* cfg.expectiDepth - limit for expectimax search
* cfg.weightFn - position weight function
*
* #constructor
*/
function expectimaxAI(brdEngine, cfg) { ... }
Which markup is to use for cfg.minimaxDepth (cfg.*) parameters?
Is it possible to document synthetic aiCfg type and put reference to it as:
* #param {aiCfg} cfg config
or somehow else?
After reading official JSDoc 2.x docs I make some hack:
/**
* #name BlindWeightRandomCfg
* #function
* #param {number} left weight
* #param {number} right weight
* #param {number} up weight
* #param {number} down weight
*/
and refer to non-existing function as:
/**
* Blind weight random AI.
*
* #param {Board} brdEngine board engine from board.js
* #param {BlindWeightRandomCfg} cfg configuration settings
* #constructor
*/
ai.BlindWeightRandom = function(brdEngine, cfg) { ... }
Now argument cfg - clickable to definition of BlindWeightRandomCfg!
UPDATE Another possibility for JSDoc 2.x:
/**
* #name BlindWeightRandomCfg
* #namespace
* #property {number} left weight
* #property {number} right weight
* #property {number} up weight
* #property {number} down weight
*/
and for JSDoc 3.x:
/**
#typedef PropertiesHash
#type {object}
#property {string} id - an ID.
#property {string} name - your name.
#property {number} age - your age.
*/
/** #type {PropertiesHash} */
var props;
Seems that #typedef is a solution. Please see other variants and at official docs.
How to mark or make reference function argument in jsdoc/jsdoc3.
For example:
/**
* Build xxx.
* cfg is optional.
*
* #param {Object} cfg config
* #function
*/
function build(engine, cfg) { ... }
What markup used to wrap cfg in cfg is optional. description?
I see one possible way by enclosing into tt HTML tag:
/**
* Repeat <tt>str</tt> several times.
* #param {string} str The string to repeat.
* #param {number} [times=1] How many times to repeat the string.
* #returns {string}
*/
repeat: function(str, times) { ... }