使用脚本标签时的 JSDoc 智能感知

Question

问题

我发现当 JSDoc 类型的代码位于项目“内部”时，JSDoc 可以很好地与智能感知和类型检查配合使用；但是，通过脚本标签 (

<script src="mylibrary.js">

) 包含 JSDoc 类型库不会提供任何智能感知、类型检查或提示。

我的目的是发布一个包含类型的库，我希望 JSDoc 能够允许我这样做，即使对于那些想要通过标签包含脚本而不是使用 NPM 安装和导入的用户来说，

.d.ts

文件会够了。

我很感激任何人都可以提供的任何见解。

假设

我的猜测是，TypeScript 检查器无法访问脚本标记中包含的代码，即使该脚本是本地的，但由于我没有看到任何直接说明这一点的内容，所以我想在这里检查我的理解。我是 TypeScript 用户，但对 JSDoc 很陌生，所以我可能会错过一些细微差别。

详情

我正在将 VSCode 与 Microsoft 的“JavaScript 和 TypeScript Nightly”插件一起使用。

我的库代码的工作原理如下：

/**
 * @preserve
 * @typedef {object} LibObj - The main library object
 * @property {string} LibObj.name - The name of the library
 */
globalThis.LibObj = {
  name: "My Library's Name"
}

当我将库代码包含到 HTML 页面中时，

LibObj

和

LibObj.name

具有

any

类型，并且我没有得到智能感知。

Answer 1

这非常简单。假设 Visual Studio Code 环境。

如果您的用户预期用途是他们将拥有

page.html

和

<script src="mylibrary.js"></script><!-- your library -->
<script src="script.js"></script><!-- their script using your library -->

那么你应该指示他们添加三斜杠指令

/// <reference path="mylibrary.js" />

在其

script.js

的开头，可选地与

// @ts-check

注释指令以及也许

//@module

JSDoc 指令一起使用。

这样，语言服务器将确定

library.js

提供了什么，并将其包含在

script.js

中的智能感知和类型检查中。