26 окт 2014 в 11:55

Всегда актуальная документация: JSDoc плагин для вставки исходного кода

Ожидает приглашения

Здравствуй, хабраюзер! Хочу поделиться с тобой небольшим 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.: Плагин писался для своих нужд, но я буду очень рад, если он кому-то пригодится.

Хабы:

JavaScript