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