JSDoc将实际代码添加到文档中

Question

你知道在JSDoc中是否有类似于<code />标签的东西吗？我需要在我的文档中添加代码片段，就像这样：

/**
 * This function does something see example below:
 *
 * var x = foo("test"); //it will show "test" message
 *
 * @param {string} str: string argument that will be shown in message
 */
function foo(str)
{
   alert(str);
}

我需要注释中的代码能够像代码一样（如果没有语法高亮，至少像预格式化文本那样显示，带有灰色背景）由JSDoc显示出来。

- Marco Demaio

Answer 1

@example http://code.google.com/p/jsdoc-toolkit/wiki/TagExample

意思是，这段内容提供了一个示例链接，可以用于说明如何使用 @example 标签来为函数、类、命名空间等创建示例。您可以访问提供的链接以获取更多详细信息。

/**
 * This function does something see example below:
 * @example
 * var x = foo("test"); //it will show "test" message
 *
 * @param {string} str: string argument that will be shown in message
 */
function foo(str)
{
   alert(str);
}

- Josh Johnson

---

从您提供的文档中可以看出：@example 标签不是用来生成“内联”示例的，如果您需要这样做，需要通过嵌入在 @description 块中的 HTML 标记来完成，例如使用 <code> 标签。 - zack

gjslint是一种强制执行Google JavaScript StyleGuide的工具，不允许使用@example标签...因此您可能需要使用<pre><code></code></pre>解决方案。 - Xantix

这也是 VS Code 智能感知支持的一种方法。https://github.com/Microsoft/vscode/issues/30062 - Peter W

VS Code（截至撰写时）似乎不支持HTML标签。:( 我尝试过<pre>和<code>，但它们都只是在Intellisense中被字面上写出来。然而，我刚刚意识到Markdown似乎也被支持了!!! 因此，用反引号(`)包围行内代码就可以了。 :) - Jonathan Benn

Answer 2

<pre><code>

....

</code></pre>

这是许多官方文档中使用的方式，例如某些工具将会对其进行语法高亮。

- Sean Kinsey

---

听起来很奇怪。这是无效的HTML。Pre元素可以包含code元素，但反过来不行。 - Quentin

@David，可能是我记错了标签的顺序 :) - Sean Kinsey

这对于TypeScript不起作用。@example答案效果很好。 - ypresto

Answer 3

Jsdoc3 有一个 markdown 插件，但默认情况下它是关闭的。通过在默认配置文件 ./node_modules/jsdoc/conf.json.EXAMPLE 中启用它...

"plugins": [
    "plugins/markdown"
],

...而且你可以很好地支持文档的语法，包括代码。Markdown使用三个反引号(```)来标记代码块。为了使用原始示例：

/**
* This function does something see example below:
* ```
* var x = foo("test"); //it will show "test" message
* ```
* @param {string} str: string argument that will be shown in message
*/

- offlinehacker

---

我已经通过 conf.json 启用了 Markdown 插件 - 有没有一种方法可以显示行内代码，即通常使用单个反引号 像这样 实现的代码？编辑：实际上它确实可以工作，只是默认情况下代码标记的样式非常简洁。 - user1063287

在 Visual Studio Code 中，Markdown 支持似乎已经自带。 - Jonathan Benn

Answer 4

您可以在JSDoc中放置任何HTML标记，它会被复制出来。以下是我使用的一个示例：

/** 
 * The ReplaceSlang method replaces the string "hi" with "hello".
 *   <script language="javascript">
 *     function testFunc() {
 *       alert(ReplaceSlang(prompt("Enter sample argument")));
 *     }
 *   </script>
 *   <input type="button" value="Test" onclick="testFunc()" />
 * @param {String} str The text to transform
 * @return {String}
 */
exports.ReplaceSlang = function(str) {
  return str.replace("hi", "hello");
};

为确保按钮不在摘要中，需要在之前加上一个句子和一个点（.）。

您需要找到一种方法将您的JavaScript文件包含在JSDoc的输出中，以便它们被加载。(否则，在JSDoc的输出中，您的代码不存在为JavaScript – 您可以修改模板：参见JsPlate文档)

- Eric

---

对不起，我刚意识到那并不是你想要做的。如果这个评论能帮到其他人，你介意我让它保留下来吗？ - Eric

Answer 5

对于jsdoc3，<code>...</code> 看起来工作正常。它可以将代码保持内联，而添加 <pre> 则会创建一个段落（这也是它应该做的）。 浏览器支持 看起来也没问题，所以我不认为有任何理由不使用它。

- SGD

Answer 6

使用@example对于大多数情况可以起作用，但是HTML保留字符需要转换为文字： < >等等，否则HTML将被呈现而不是显示为代码。

- Lee Goddard