将内容动态注入 JSDoc @example

Question

我正在使用 JSDoc 来记录我的 javascript API。

我有一个@example，我在其中展示了一个最小化的加载程序脚本（类似于 Google Analytics 脚本）。加载器脚本从 https://<server>/myProduct/lib/script.js 加载额外的 javascript。

我的 JSDoc 文档与 myProduct 捆绑在一起，因此并列有 /myProduct/lib/script.js 和 /myProduct/docs/。但是，myProduct 可以由我的客户在任何地方托管，所以我不知道<server> 是什么。

我希望能够使用document.location.href 来检测当前浏览器 URL，并在我的@example 中显示一个工作加载器脚本，以便客户可以简单地从文档中复制和粘贴一个工作脚本，而无需手动编辑<server> 部分。

我的问题是： JSDoc 是否提供任何方法将内容动态注入@example？

我可以手动编辑 JSDoc 输出并手动包含一些自定义 javascript，它将<server> 替换为运行时的实际当前服务器。但是，每次我的文档更新时都这样做很乏味。

Answer 1

不，JsDoc 不提供注入外部内容，虽然在文档生成过程中创建一个 JsDoc 插件来包含外部内容当然是可能的，但我认为这不会让你到达你需要的地方。

我认为最简单的答案是对 JsDoc 的输出进行后处理以添加一个简单的脚本，例如

<script>
// retrieve the hostname from the current url.
const getServiceHostName = () => 
  document.location.href.replace(/http:\/\/([\/]+)\/.+$/, '$1');

// replace the content of the span#service-host with the current hostname.
document.onload = function () {
  document.getElementById("service-host").textContent=getServiceHostName();
};
</script>

到您的 html 文件，就在 </body> 标记上方。

然后，在示例内容中，插入 <span id="service-host"></span> 您希望服务主机名出现的位置。

另一种方法可能是利用 JsDoc 将附加到 @description 标记的内容直接传递到 html 输出这一事实。

所以，这似乎符合预期：

/**
 * Hostname: "<span id="service-host">hostname</span>"
 *
 * <script src="https://code.jquery.com/jquery-3.6.0.min.js"
 *   integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4="
 *   crossorigin="anonymous"></script>
 *
 * <script>
 *   $(document).ready(function() {
 *     $("#service-host").html(document.location.href);
 *   });
 * </script>
 *
 * @name How-To-Monkey-Patch-JsDoc
 *
 */

请注意，@example 的内容在 html 输出中包含在 <pre><code>...</code></pre> 中，这肯定会给您带来问题，但是使用上面的代码对 html 内联进行后处理应该很容易，方法是添加一些可识别的标记（可能是[[HOSTNAME]]）到示例内容中并在文档加载时，将其替换为所需的值。

另请注意，这种方法可能会使您的文档面临安全问题，这就是我使用上述第一种解决方案的原因。