如何在VSCode的JSDoc中转义@符号？规避解析异常

我刚好碰到过这个问题，太懂你的困扰了——用HTML转义码在代码块里显示成@确实很别扭，完全不符合阅读习惯。给你两个实用的方案：

• 在JSDoc描述文本中转义@：直接在@符号前加一个反斜杠\@。VSCode的JSDoc解析器会识别这个转义，不会把它当成JSDoc标签处理，而且最终显示的时候会自动渲染成正常的@符号，完全不用依赖HTML转义。举个例子：

  /**
   * 这个函数需要你传入带\@前缀的标识符，比如\@userID
   * @param {string} id 带\@前缀的用户ID
   * @returns {boolean} 验证结果
   */
  function validateId(id) {
    return id.startsWith('@');
  }
  

  这样写的话，VSCode既不会把描述里的\@误解析为标签，hover查看文档的时候也能看到正常的@符号。

• 在代码示例中保留@：如果是在JSDoc的代码块（用```包裹）里的@符号，其实不需要额外转义——只要把代码放在Markdown风格的代码块里，VSCode的JSDoc解析器会跳过代码块内的标签解析，直接显示原始的@符号。比如：

  /**
   * 使用示例：
   * ```javascript
   * // 正确的调用方式
   * validateId('@12345');
   * ```
   */
  

  这里代码块里的@会正常显示，不会被解析成JSDoc标签。

这两种方法都能完美避开HTML转义码的问题，而且完全适配VSCode的JSDoc解析逻辑，你可以根据场景选着用~

内容的提问来源于stack exchange，提问作者Jason Kuhrt