Здравствуй, читатель! Хочу поделиться с тобой небольшим JSDoc плагином для вставки в документацию примеров кода из существующих JavaScript функций — examplecode.
Проблема и задача
В одной из JavaScript библиотек, над которыми я сейчас работаю, было принято решение обновить документацию и сделать это захотелось максимально качественно, всегда актуальную и легко обновляемую.
IDE (например PhpStorm/WebStorm) ошибки в типах и количестве параметрах сразу увидят и укажут на неактуальность документации, но вставляемые примеры кода (через тег example) распознаются IDE как plain text — про них можно легко забыть и документация станет не актуальной.
Решение
Было принято решение писать примеры в виде отдельных JavaScript функций и запускать их в Unit тестах. Собственно, решение не ново и много где используется, но вот вставить такой код используя стандарт JSDoc не удастся. В стандарте JSDoc есть только туториалы, но их формат не подходит для данной задачи.
Плагин @examplecode
Плагин позволяет добавлять к свойствам и методам тег examplecode с указанием ссылки на функцию. После этого плагин вставит код функций как стандартный тег example.
Инструкция по установке
Скачайте плагин examplecode.js и поместите его в директорию с конфигурационном файлом. В нём необходимо разрешить использование нестандартных тегов (чтобы плагин увидел тег examplecode) и добавить плагин в раздел plugins. Пример файла config.js:
{
"tags": {
"allowUnknownTags": true
},
"source": {
"include": [
"source/",
"examples/"
],
"includePattern": "\.js$"
},
"plugins": [
"examplecode"
]
}
Пример использования
Необходимо создать функцию, код которой вы хотите использовать как пример для документации. Затем добавить тег @examplecode в метод, к которому относится пример. В описании тега нужно указать название метода (SayExample) или неймспейс + название, если функция не глобальная (examples.person.SayExample).
Значения по-умолчанию, указанные в JSDoc'e примера будут добавлены в начало примера. Смотрим пример:
// -------- Example function --------
/**
* @function SayExample
* @param {string} [message='Hello World!']
*/
function SayExample(message) {
console.log('You message: ' + message);
}
// -------- Source code -------------
/**
* Creates a new Person.
* @class
*/
var Person = function() {
};
/**
* Say method
* @examplecode SayExample
* @function
*/
Person.prototype.say = function() {
};
Для генератора документации такой код будет эквивалентен следующему:
/**
* Creates a new Person.
* @class
*/
var Person = function() {
};
/**
* Say method
* @example
* var message = 'Hello World!';
*
* console.log('You message: ' + message);
* @function
*/
Person.prototype.say = function() {
};
Плагин имеет лицензию MIT и размещен на GitHub.
P.S.: Плагин писался для своих нужд, но я буду очень рад, если он кому-то пригодится.
