如何在函数内部添加有效JSDoc注释？是否有jsconfig.json配置可用？

一、为什么函数内部的JSDoc注释无效？ #

VS Code这类编辑器的JSDoc解析逻辑是把注释和紧邻的函数/变量绑定，默认只认函数声明上方的块级注释。你把带@param、@return的注释写在函数内部，编辑器只会当它是普通的代码注释，不会关联到函数本身，自然没法生效。

二、有没有jsconfig.json配置能让内部注释生效？ #

目前没有官方支持的配置项能改这个规则。不管是JSDoc的规范还是编辑器的实现，都是优先关联函数声明前的注释——强行改解析逻辑会打破通用的代码注释约定，反而让代码可读性变差。

三、可行的替代方案 #

如果确实要在函数内部加注释（比如复杂逻辑的分段说明），可以这么做：

• 函数上方保留标准JSDoc（用来做类型提示、函数整体说明）
• 函数内部用单行//或块级/** ... */写逻辑注释，这类注释不用加@param、@return标签，只用来解释具体代码就行

示例代码：

/**
 * 移动数组元素位置
 * @param {Number} index - 待移动元素的索引
 * @return {Array} 处理后的新数组
 */
function arrayMove(index) {
  // 复制原数组，避免修改原始数据
  const newArr = [...this.arr];
  /**
   * 内部逻辑注释：判断索引是否合法
   * 越界则直接返回原数组副本
   */
  if (index < 0 || index >= newArr.length) return newArr;
  // ...后续处理逻辑
}

内容的提问来源于stack exchange，提问作者Ricky Boyce