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

使用

<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

您可以在JSDoc中放置任何HTML，然后将其复制出来。以下是我使用的一个例子：

/** 
 * 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文件包含在JSDoc的输出中，以便加载它们。（您的代码在JSDoc的输出中不存在为javascript - 您可以修改模板：请参阅JsPlate documentation）

Answer 4

jsdoc3 <code>...</code>似乎工作正常。它还保持代码内联，而在<pre>中添加会创建一个段落（这应该是它应该做的）。 Browser support似乎没问题，所以我认为没有理由不使用它。

Answer 5

使用@example适用于大多数情况，但HTML保留字符需要转换为文字：< >等等，否则HTML将呈现而不会显示为代码

JSDoc在文档中添加实际代码

5 个答案: