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 将注释中的代码显示为代码（如果没有突出显示语法，至少像预格式化或带有灰色背景的东西）。

Answer 1

@example

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

/**
 * 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);
}

Answer 2

使用

<pre><code>

....

</code></pre>

这是许多官方文档中使用的内容，例如可以使用某些工具接收语法高亮显示

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
*/

Answer 4

您可以将任何 HTML 放入 JSDoc 中，它将被复制出来。这是我使用的一个例子：

/** 
 * 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 文档）

Answer 5

对于 jsdoc3

<code>...</code>

似乎工作得很好。它还使代码保持内联，同时添加

<pre>

创建一个段落（无论如何这是它应该做的）。 浏览器支持似乎还不错，所以我认为没有任何理由不使用它。

Answer 6

使用 @example 适用于大多数情况，但 HTML 保留字符需要转换为 HTML 实体：

<

>

等，否则 HTML 将被渲染并且不会显示为代码。

来自链接文档：

/**
 * Solves equations of the form a * x = b
 * @example
 * // returns 2
 * globalNS.method1(5, 10);
 * @example
 * // returns 3
 * globalNS.method(5, 15);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};

带有标题的示例：

/**
 * Solves equations of the form a * x = b
 * @example <caption>Example usage of method1.</caption>
 * // returns 2
 * globalNS.method1(5, 10);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};