在文档中添加真正的代码

您知道 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);
}

我需要 JDoc 将注释中的代码显示为代码(如果没有突出显示语法，至少像预先格式化或灰色背景的代码)。

39853 次浏览
小开
最佳答案

使用

<pre><code>


....


</code></pre>

这是许多官方文档中使用的方法，例如，它将使用一些工具接收语法突出显示

小开

@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);
}
小开

你可以把任何 HTML 放到 JDoc 中，它就会被拷贝出来:

/**
* The ReplaceSlang method replaces the string &quot;hi&quot; with &quot;hello&quot;.
*   <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 文件包含在 JDoc 的输出中，以便加载它们。(否则，您的代码不会以 javascript 的形式存在于 JSDoc 的输出中——您可以为此修改模板: 请参阅 JsPlate 文档)

小开

使用 @ example在大多数情况下都可以工作，但是 HTML 保留字符需要转换为字面值: &lt; &gt;等等，否则 HTML 将被呈现而不显示为代码。

小开

对于 Jsdoc3 <code>...</code>似乎工作正常。它还保持代码内联，同时在 <pre>中添加代码创建一个段落(无论如何这也是它应该做的)。浏览器支持看起来不错，所以我没有看到任何不使用它的理由。

小开

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

提交答案