Documenting Object with methods and their return values in JSDoc - jsdoc

Question

I have a paging controller factory, that returns a paging controller Object with a bunch of methods (for the view to interact with, especially when an end-user does an action like navigate to a different page or enter some search text). It is defined something like:
/**
* Returns a paging controller object with data
* #param {Object[]} data
* #param {string} prop the property containing that data. If it's a function, it should be no-args.
* #param {filterFunc} filterer a callback that filters the data
*/
function pagingControllerFor(data, prop, filterer) {
let _currentPage = 0
let _filterFunc = filterer
let _stateChange = false
let _data;
const _ITEMS_PER_PAGE = 50
let _selectAllChecked = [];
/**
* Getter for all the data. Useful for debugging.
*/
function getAllData() {
if (prop) {
if (typeof data[prop] === 'function') {
return data[prop]()
}
return data[prop]
}
return data
}
/**
* Always returns fresh data for the controller
*/
function getData() {
let data = getAllData()
if (_filterFunc) {
if ((_stateChange) || (!_data)) {
_data = data.filter(_filterFunc)
_selectAllChecked = Array(Math.ceil(_data.length / _ITEMS_PER_PAGE)).fill(false)
_stateChange = false
}
return _data
}
return data
}
return {
/* a whole bunch of methods irrelevant to my use case on here */
getCurrentPageData : () => getData().slice(_currentPage * _ITEMS_PER_PAGE, (_currentPage + 1) * _ITEMS_PER_PAGE),
// get/set current "Select All" checkbox state
isCurrentSelectAllChecked : () => _selectAllChecked[_currentPage],
setCurrentSelectAllChecked : (checked) => _selectAllChecked[_currentPage] = checked
}
}
I am writing an event-binder for the "Select/Deselect All" checkboxes on the view being paginated. It is, as of the time I wrote this, defined to be:
/**
* Binds clicks on the current "Select/Deselect All" checkbox to the controller
* #param {string} modalType
* #param {{ getCurrentPageData : () => Array<{IsSelectedOnModal : boolean}>, setCurrentSelectAllChecked : () => boolean }} controller
* #param {Function} callback
*/
function bindToggleSelectAllEvent(modalType, controller, callback) {
callback = callback || bindToggleSelectAllEvent
const modalSelector = `#${modalType}-selector-modal`
$(`#toggle-all-${(modalType === ITEM) ? 'items' : 'categories'}-selected`)
.off('change')
.on('change', function() {
// get the state of this
let isChecked = $(this).prop('checked')
// change the selection state of all current items/categories in the controller to that state
controller.getCurrentPageData().forEach((data) => {
data.IsSelectedOnModal = isChecked
})
// tell the controller the new state of this "Select All" checkbox
controller.setCurrentSelectAllChecked(isChecked)
// Re-render modal?!
// TODO: implement this
})
}
VSCode knows what I'm doing, as it detects the relevant methods of controller, which I have specified.
However, JSDoc doesn't, for some reason:
ERROR: Unable to parse a tag's type expression for source file [my-project-path]\static\js\menu\edit\index.js in line 433 with tag title "param" and text "{{ getCurrentPageData : () => Array<{IsSelectedOnModal : boolean}>, setCurrentSelectAllChecked : () => boolean }} controller": Invalid type expression "{ getCurrentPageData : () => Array<{IsSelectedOnModal : boolean}>, setCurrentSelectAllChecked : () => boolean }": Expected "," or "}" but "=" found.
ERROR: Unable to parse a tag's type expression for source file [my-project-path]\static\js\menu\edit\index.js in line 439 with tag title "param" and text "{{ getCurrentPageData : () => Array<{IsSelectedOnModal : boolean}>, setCurrentSelectAllChecked : () => boolean }} controller": Invalid type expression "{ getCurrentPageData : () => Array<{IsSelectedOnModal : boolean}>, setCurrentSelectAllChecked : () => boolean }": Expected "," or "}" but "=" found.
What should I do about this?

Answer 1

VS Code support TypeScript types in JS Docs but the JS Doc tool only supports Closure types.
I believe that the arrow function type expressions that you are using are valid TypeScript types but cannot be understood by the JSDoc tool. Try using the function(): function type syntax instead
#param {{ getCurrentPageData : function(): Array<{IsSelectedOnModal : boolean}> }} controller