jsdoc - 在 JSDoc 中用方法及其返回值记录对象

Question

我有一个分页 Controller 工厂，它返回一个带有一堆方法的分页 Controller 对象(用于与 View 交互，特别是当最终用户执行导航到不同页面或输入一些搜索文本等操作时) 。它的定义类似于:

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

}

我正在为正在分页的 View 上的“全选/取消全选”复选框编写一个事件绑定(bind)器。截至我撰写本文时，它的定义是:

/**
 * 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 Doc 中的 TypeScript 类型，但 JS Doc 工具仅支持 Closure types .

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

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