在 JSDoc 中使用方法及其 return 值记录对象

Question

我有一个分页控制器工厂，returns 一个带有一堆方法的分页控制器对象（用于与视图交互，尤其是当最终用户执行导航到其他页面等操作时或输入一些搜索文本）。它的定义类似于：

/**
 * 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
    }

}

我正在为正在分页的视图上的 "Select/Deselect All" 复选框编写一个事件绑定程序。截至我撰写本文时，它定义为：

/**
 * 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知道我在做什么，因为它检测到我指定的controller的相关方法。

但是，由于某些原因，JSDoc 没有：

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.

我该怎么办？

Answer 1

VS Code 支持 JS Docs 中的 TypeScript 类型，但 JS Doc 工具仅支持 Closure types.

我相信您使用的箭头函数类型表达式是有效的 TypeScript 类型，但 JSDoc 工具无法理解。尝试使用 function(): function type syntax 而不是

@param {{ getCurrentPageData : function(): Array<{IsSelectedOnModal : boolean}> }} controller

在 JSDoc 中使用方法及其 return 值记录对象

Documenting Object with methods and their return values in JSDoc

jsdoc