Простое документирование JavaScript с помощью YUIDocs и Grunt.js

Документирование кода — неприятный, но необходимый этап работы над приложением. Хорошо документированная и актуализированная кодовая база поможет новым разработчикам лучше понять ваш код, а также усилит контроль над отдельными составляющими вашего приложения.

YUIDoc

YUIDoc — это относительно новое приложение на платформе Node.js, позволяющее распарсить некоторые комментарии в JavaScript и сгенерировать на их основе документацию для API. Ниже будут рассмотрены основы синтаксиса для документирования.

YUIDoc позволяет отмечать части приложения, которые должны быть использованы в последующем документировании.

Например, если вам нужно составить документацию для чего-то на подобии jQuery, это будет выглядеть так:

/**
* Главный класс jQuery.
* @class jQuery
* @param {String} selector Селектор элемента.
* @param {String} [context] Контекст для поиска.
*/
jQuery = /* … */

Затем таким же образом можно задокументировать методы:

/**
* Использование AJAX для поиска данных
* @method ajax
* @param {Object} options Опции запроса
    @param {String} options.url Адрес запроса.
    @param {String} [options.type=get] Тип запроса, по умолчанию `GET`.
* @example
Здесь, кстати, можно использовать синтаксис markdown!

    jQuery.ajax({ 
        url: 'foo/'
    });

* @return {jQuery.Deferred}
*/ 
jQuery.ajax = /* … */

У YUIDoc также есть масса возможностей, например:

• @extend указание класса, который наследуется данным классом;
• @for изменение контекста метода если он был добавлен в документацию отдельно от своего класса;
• @event документирование событий вашего приложения;
• @constructor обозначает, что функция является конструктором и вызывается при создании экземпляров класса;
• @static обозначает, что это статический класс или метод;
• И многое другое.

Ознакомьтесь с синтаксисом, чтобы узнать о всех возможностях приложения.

Создание документации с помощью Grunt

Gruntjs — это сборщик проектов для NodeJS. С его помощью можно выполнить множество задач для кода, таких как проверка качества кода (JSHint), конкатенация, минификация, и т.д. Для Grunt прописаны сотни задач.

Для YUIDoc есть задача под именем grunt-contrib-yuidoc. Чтобы использовать YUIDoc в своём проекте, прочтите про азы настройки проекта Gruntjs на http://gruntjs.com/getting-started. Выполните следующую команду:

npm install grunt-contrib-yuidoc --save

Затем обновите ваш Gruntfile.js следующим кодом:

grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    yuidoc: {
        all: {
            name: '<%= pkg.name %>',
            description: '<%= pkg.description %>',
            version: '<%= pkg.version %>',
            url: '<%= pkg.homepage %>',
            options: {
                paths: ['path/to/your/scripts'],
                outdir: './docs/'
            }
        }
    }
});

grunt.loadNpmTasks("grunt-contrib-yuidoc");

grunt.registerTask("docs", ["yuidoc"]);

Теперь вы можете запустить grunt docs и, вуаля, ваша документация сгенерирована и сохранена в outdir.

Заключение

Документация действительно очень важна для проекта. Хоть её составление может показаться трудоёмкой задачей, в конце концов, оно того стоит. Большинство лучших библиотек с открытым кодом завоевали популярность благодаря своей документации. Не важно, открытый у проекта код, или нет, хорошая документация играет очень важную роль в возможности поддержки приложения.