JSDoc在文档中添加实际代码

Question

你知道<code />JSDoc中是否有某种标签吗？我需要在我的文档中添加代码片段,如下所示:

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

使用

<pre><code>

....

</code></pre>

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

Answer 2

@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 3

Jsdoc3有一个降价插件,但默认情况下它是关闭的../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

你可以在 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 文档）

Answer 5

使用@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;
};

Answer 6

对于jsdoc3 <code>...</code>似乎工作得很好。它还使代码保持内联，同时添加<pre>创建一个段落（无论如何它应该这样做）。浏览器支持似乎没问题，所以我看不出有任何理由不使用它。