将内容动态注入 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 插件以在文档生成期间包含外部内容当然是可能的，但我认为这不会让您到达需要的位置.

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

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

// 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> 中，这肯定会给您带来麻烦，但应该很容易 post-使用上面的代码处理 html 内联，方法是在示例内容中添加一些可识别的标记（可能是 [[HOSTNAME]]），并在文档加载时将其替换为所需的值。

另请注意，此方法可能会使您的文档出现安全问题，这就是为什么我会使用上面的第一个解决方案。

将内容动态注入 JSDoc @example

Dynamically inject content into JSDoc @example

jsdoc