文档对象在JSDoc方法及其返回值

Question

我有一个寻呼控制器工厂，返回一个寻呼控制器对象了一堆的方法（视图与互动，尤其是当最终用户确实喜欢导航到不同的页面或输入一些搜索文本的动作）。它的定义是这样的：

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

}

我写一个事件基料上是分页视图中的“选择/取消全部”复选框。它是，因为时间我写了这个，定义为：

/**
 * 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的代码支持打字稿类型的JS文件，但JS文件工具仅支持Closure types。

我相信，你正在使用箭头函数类型的表达式是有效的打字稿类型，但不能由JSDoc工具来理解。尝试使用function(): function type syntax代替

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