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>

....

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

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

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

Answer 5

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

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

Answer 6

Использование @ example работает в большинстве случаев, но зарезервированные символы HTML необходимо преобразовать в литералы: < > и т. Д., Иначе HTML будет отображаться и не отображаться как код.