JSDoc добавляет реальный код в документацию

Знаете ли вы, есть ли какой-то код <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 в качестве кода (если не синтаксис выделен, по крайней мере, как предварительно форматированный или что-то с серым фоном).

Ответы

Ответ 1

Использование

<pre><code>

....

</code></pre>

Это то, что используется во многих официальных документах, и будет, например, получать синтаксический заголовок с помощью некоторых инструментов

Ответ 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);
}

Ответ 3

Jsdoc3 имеет плагин markdown, но по умолчанию он отключен. Включите его конфигурационный файл по умолчанию ./node_modules/jsdoc/conf.json.EXAMPLE через...

"plugins": [
    "plugins/markdown"
],

... и у вас хорошая поддержка синтаксиса для документов, в том числе и для кода. Markdown использует три backticks (```) для разграничения блоков кода. Для использования исходного примера:

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

Ответ 4

Вы можете поместить любой HTML в JSDoc, и он будет скопирован. Вот пример того, что я использую:

/** 
 * 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, чтобы они были загружены. (Ваш код в противном случае не существует как javascript в выводе JSDoc - вы можете изменить шаблон для этого: см. Документация JsPlate)

Ответ 5

Использование @example работает в большинстве случаев, но зарезервированные символы HTML должны быть переведены в литералы: &lt; &gt; и так далее, иначе HTML будет отображаться и не отображаться в виде кода.

Ответ 6

Для jsdoc3 <code>...</code>, похоже, отлично работает. Он также сохраняет код в строке, а добавление в <pre> создает абзац (что и должно делать в любом случае). Поддержка браузера, кажется, в порядке, поэтому я не вижу причин, чтобы не использовать ее.