Javascript JSDoc 在文档中添加真实代码
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/2961310/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
JSDoc adding real code in documentation
提问by Marco Demaio
Do you know if there is some sort of <code />tag in JSDoc? I need to add pieces of code in my documentation like this:
你知道<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);
}
I need the code in the comments to be displayed by JSDoc as code (if not syntax highlighted, at least like pre-formatted or something with grey background).
我需要注释中的代码由 JSDoc 显示为代码（如果没有突出显示语法，至少像预先格式化或带有灰色背景的东西）。
采纳答案by Sean Kinsey
Use
用
<pre><code>
....
</code></pre>
This is whats used in many official docs, and will for instance receive syntax hightlighting with some tools
这是许多官方文档中使用的内容，例如将使用某些工具接收语法高亮显示
回答by Josh Johnson
@examplehttp://code.google.com/p/jsdoc-toolkit/wiki/TagExample
@examplehttp://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);
}
回答by offlinehacker
Jsdoc3 has a markdown plugin but it is turned off by default. Enable it the default config file ./node_modules/jsdoc/conf.json.EXAMPLEvia ...
Jsdoc3 有一个 markdown 插件，但默认是关闭的。./node_modules/jsdoc/conf.json.EXAMPLE通过...启用默认配置文件
"plugins": [
"plugins/markdown"
],
... and you have nice syntax support for docs, including for code. Markdown uses three backticks (```) to demarcate code blocks. For to use the original example:
...并且您对文档（包括代码）有很好的语法支持。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
*/
回答by Eric
You can put any HTML in JSDoc and it will be copied out. Heres an example of what I use:
你可以在 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");
};
To make sure the button is not in the summary, add a sentence and a dot (.) before it.
要确保按钮不在摘要中，请在其前添加一个句子和一个点 (.)。
You need to find some way to include your javascript file in the output of JSDoc so that they are loaded. (Your code otherwise does not exist as javascript in the output of JSDoc – you can modify the template for that : see JsPlate documentation)
您需要找到某种方法将您的 javascript 文件包含在 JSDoc 的输出中，以便加载它们。（否则，您的代码在 JSDoc 的输出中不作为 javascript 存在 – 您可以为此修改模板：请参阅JsPlate 文档）
回答by SGD
For jsdoc3<code>...</code>seems to work just fine. It also keeps the code inline while adding in <pre>creates a paragraph (which is what it should do anyways). Browser supportseems to be ok so I don't see any reason to not use it.
对于jsdoc3<code>...</code>似乎工作得很好。它还使代码保持内联，同时添加<pre>创建一个段落（无论如何它应该这样做）。浏览器支持似乎没问题，所以我看不出有任何理由不使用它。
