О плагинах JSDoc

Содержание

• Создание и включение плагина
• Создание плагинов для JSDoc 3
  • Обработчики событий
  • Определения тегов
  • Посетители узлов
• Отчет об ошибках

Создание и включение плагина

Для создания и включения нового плагина JSDoc требуется два шага:

1. Создайте JavaScript-модуль, содержащий код вашего плагина.
2. Включите этот модуль в массив plugins файла конфигурации JSDoc. Вы можете указать абсолютный или относительный путь. Если вы используете относительный путь, JSDoc ищет плагин в текущем каталоге, каталоге расположения конфигурационного файла и каталоге JSDoc в указанном порядке.

Например, если ваш плагин определен в файле plugins/shout.js в текущем каталоге, вы добавите строку plugins/shout в массив plugins в файле конфигурации JSDoc:

{
    "plugins": ["plugins/shout"]
}

JSDoc выполняет плагины в порядке их перечисления в файле конфигурации.

Создание плагинов для JSDoc 3

Система плагинов JSDoc 3 предоставляет расширенный контроль над процессом парсинга. Плагин может повлиять на результаты парсинга, выполнив любое из следующих действий:

• Определение обработчиков событий
• Определение тегов
• Определение посетителя для узлов абстрактного синтаксического дерева

Обработчики событий

На самом высоком уровне плагин может зарегистрировать обработчики для определенных событий, которые JSDoc запускает. JSDoc передаст объект события обработчику. Ваш модуль плагина должен экспортировать объект handlers , содержащий ваш обработчик, следующим образом:

exports.handlers = {
    newDoclet: function(e) {
        // Do something when we see a new doclet
    }
};

JSDoc запускает события в том же порядке, что и основной код.

Плагин обработчика событий может остановить выполнение последующих плагинов, установив свойство stopPropagation в объекте события (e.stopPropagation = true). Плагин может остановить запуск события, установив свойство preventDefault (e.preventDefault = true).

Событие: parseBegin

Событие parseBegin запускается перед тем, как JSDoc начнет загрузку и парсинг исходных файлов. Ваш плагин может управлять файлами, которые JSDoc будет парсить, изменяя содержимое события.

Примечание: Это событие запускается в JSDoc 3.2 и более поздних версиях.

Объект события содержит следующие свойства:

• sourcefiles: Массив путей к исходным файлам, которые будут обработаны.

Событие: fileBegin

Событие fileBegin запускается, когда парсер собирается обработать файл. Ваш плагин может использовать это событие для запуска инициализации по файлам при необходимости.

Объект события содержит следующие свойства:

• filename: Имя файла.

Событие: beforeParse

Событие beforeParse запускается перед началом парсинга. Плагины могут использовать этот метод для изменения исходного кода, который будет обработано. Например, ваш плагин может добавить комментарий JSDoc или удалить теги предварительной обработки, которые не являются допустимым JavaScript.

Объект события содержит следующие свойства:

• filename: Имя файла.
• source: Содержимое файла.

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

exports.handlers = {
    beforeParse: function(e) {
        var extraDoc = [
            '/**',
            ' * Function provided by a superclass.',
            ' * @name superFunc',
            ' * @memberof ui.mywidget',
            ' * @function',
            ' */'
        ];
        e.source += extraDoc.join('\n');
    }
};

Событие: jsdocCommentFound

Событие jsdocCommentFound запускается всякий раз, когда находится комментарий JSDoc. Комментарий может или не может быть связан с каким-либо кодом. Вы можете использовать это событие для изменения содержимого комментария перед его обработкой.

Объект события содержит следующие свойства:

• filename: Имя файла.
• comment: Текст комментария JSDoc.
• lineno: Номер строки, в которой был найден комментарий.
• columnno: Номер столбца, в котором был найден комментарий. Доступно в JSDoc 3.5.0 и более поздних версиях.

Событие: symbolFound

Событие symbolFound запускается, когда парсер сталкивается с символом в коде, который может потребоваться документировать. Например, парсер запускает событие symbolFound для каждой переменной, функции и объекта-литерала в исходном файле.

Объект события содержит следующие свойства:

• filename: Имя файла.
• comment: Текст комментария, связанного с символом (если есть).
• id: Уникальный идентификатор символа.
• lineno: Номер строки, в которой был найден символ.
• columnno: Номер столбца, в котором был найден символ. Доступно в JSDoc 3.5.0 и более поздних версиях.
• range: Массив, содержащий числовой индекс начального и конечного символов в исходном файле, связанных со символом.
• astnode: Узел символа из абстрактного синтаксического дерева.
• code: Объект со подробной информацией о коде. Этот объект обычно содержит свойства name, type, и node. Объект также может иметь свойства value, paramnames, или funcscope в зависимости от символа.

Событие: newDoclet

Событие newDoclet — это событие высшего уровня. Оно запускается при создании нового объекта документации. Это означает, что комментарий JSDoc или символ были обработаны, и был создан фактический объект документации, который будет передан шаблону.

Объект события содержит следующие свойства:

• doclet: Созданный новый объект документации.

Свойства объекта документации могут отличаться в зависимости от комментария или символа, которые он представляет. Некоторые распространенные свойства, которые вы, вероятно, увидите, включают:

• comment: Текст комментария JSDoc или пустая строка, если символ не задокументирован.
• meta: Объект, описывающий, как объект документации относится к исходному файлу (например, расположение в исходном файле).
• description: Описание документируемого символа.
• kind: Тип документируемого символа (например, class или function).
• name: Короткое имя символа (например, myMethod).
• longname: Полное имя, включая информацию о членстве (например, MyClass#myMethod).
• memberof: Модуль, пространство имен или класс, к которому принадлежит этот символ (например, MyClass), или пустая строка, если у символа нет родителя.
• scope: Область символа в его родительском элементе (например, global, static, instance, или inner).
• undocumented: Установлено в true, если у символа не было комментария JSDoc.
• defaultvalue: Значение по умолчанию для символа.
• type: Объект, содержащий детали о типе символа.
• params: Объект, содержащий список параметров функции.
• tags: Объект, содержащий список тегов, которые JSDoc не распознал. Доступно только если allowUnknownTags установлено в true в файле конфигурации JSDoc.

Чтобы увидеть объекты документации, которые JSDoc генерирует для вашего кода, запустите JSDoc с опцией командной строки -X.

Ниже приведен пример обработчика newDoclet, который выводит описания:

exports.handlers = {
    newDoclet: function(e) {
        // e.doclet will refer to the newly created doclet
        // you can read and modify properties of that doclet if you wish
        if (typeof e.doclet.description === 'string') {
            e.doclet.description = e.doclet.description.toUpperCase();
        }
    }
};

Событие: fileComplete

Событие fileComplete запускается после того, как парсер завершил обработку файла. Ваш плагин может использовать это событие для запуска очистки по файлам.

Объект события содержит следующие свойства:

• filename: Имя файла.
• source: Содержимое файла.

Событие: parseComplete

Событие parseComplete запускается после того, как JSDoc обработает все указанные исходные файлы.

Примечание: Это событие запускается в JSDoc 3.2 и более поздних версиях.

Объект события содержит следующие свойства:

• sourcefiles: Массив путей к исходным файлам, которые были обработаны.
• doclets: Массив объектов документации. См. newDoclet событие для получения подробной информации о свойствах каждого объекта документации. Доступно в JSDoc 3.2.1 и более поздних версиях.

Событие: processingComplete

Событие processingComplete запускается после того, как JSDoc обновит результаты парсинга, чтобы отразить унаследованные и заимствованные символы.

Примечание: Это событие запускается в JSDoc 3.2.1 и более поздних версиях.

Объект события содержит следующие свойства:

• doclets: Массив объектов документации. См. newDoclet событие для получения подробной информации о свойствах каждого объекта документации.

Определения тегов

Добавление тегов в словарь тегов — это способ средней степени влияния на создание документации. Перед запуском события newDoclet, блоки комментариев JSDoc анализируются для определения описания и любых тегов JSDoc, которые могут присутствовать. Когда тег найден, если он определен в словаре тегов, ему предоставляется возможность изменить объект документации.

Плагины могут определять теги, экспортируя функцию defineTags. Эта функция будет передана словарь, который можно использовать для определения тегов, как показано ниже:

exports.defineTags = function(dictionary) {
    // define tags here
};

Словарь

Словарь предоставляет следующие методы:

• defineTag(title, opts): Используется для определения тегов. Первый параметр — имя тега (например, param или overview). Второй — объект, содержащий опции для тега. Вы можете включить любые из следующих опций; значение по умолчанию для каждой опции — false:
  • canHaveType (boolean): Устанавливается в true, если текст тега может содержать выражение типа (например, {string} в @param {string} name - Description).
  • canHaveName (boolean): Устанавливается в true, если текст тега может содержать имя (например, name в @param {string} name - Description).
  • isNamespace (boolean): Устанавливается в true, если тег должен применяться к длинному имени doclet в качестве пространства имён. Например, тег @module устанавливает эту опцию в true, а использование тега @module myModuleName приводит к длинному имени module:myModuleName.
  • mustHaveValue (boolean): Устанавливается в true, если тег должен иметь значение (например, TheName в @name TheName).
  • mustNotHaveDescription (boolean): Устанавливается в true если тег может иметь значение, но не должен иметь описание (например, TheDescription в @tag {typeExpr} TheDescription).
  • mustNotHaveValue (boolean): Устанавливается в true если тег не должен иметь значение.
  • onTagged (function): Функция обратного вызова, выполняемая при обнаружении тега. Функции передаются два параметра: doclet и объект тега.
• lookUp(tagName): Получает объект тега по имени. Возвращает объект тега, включая его опции, или false если тег не определён.
• isNamespace(tagName): Возвращает true если тег применяется к длинному имени doclet в качестве пространства имён.
• normalise(tagName): Возвращает каноническое имя тега. Например, тег @const является синонимом @constant; в результате, если вы вызовете normalise('const'), он вернёт строку constant.
• normalize(tagName): Синоним для normalise. Доступно в JSDoc 3.3.0 и более поздних версиях.

Обратный вызов тега onTagged может изменять содержимое doclet или тега.

dictionary.defineTag('instance', {
    onTagged: function(doclet, tag) {
        doclet.scope = "instance";
    }
});

Метод defineTag возвращает объект Tag, у которого есть метод synonym, который может использоваться для объявления синонима для тега.

dictionary.defineTag('exception', { /* options for exception tag */ })
    .synonym('throws');

Посетители узлов

На самом низком уровне авторы плагинов могут обрабатывать каждый узел в дереве абстрактного синтаксиса (AST), определив посетителя узла, который будет посещать каждый узел. С помощью плагина посетителя узлов можно изменять комментарии и вызывать события парсера для любого произвольного фрагмента кода.

Плагины могут определить посетителя узла, экспортировав объект astNodeVisitor, который содержит функцию visitNode, как показано ниже:

exports.astNodeVisitor = {
    visitNode: function(node, e, parser, currentSourceName) {
        // do all sorts of crazy things here
    }
};

Функция вызывается для каждого узла со следующими параметрами:

• node: Узел AST. Узлы AST — это JavaScript-объекты, использующие формат, определённый спецификацией ESTree. Вы можете использовать AST Explorer, чтобы увидеть AST, который будет создан для вашего исходного кода. Начиная с версии 3.5.0, JSDoc использует текущую версию парсера Babylon со всеми включёнными плагинами.
• e: Событие. Если узел — такой, который обрабатывает парсер, объект события уже будет заполнен теми же данными, что описаны в событии symbolFound выше. В противном случае, это будет пустой объект, на котором можно установить различные свойства.
• parser: Экземпляр парсера JSDoc.
• currentSourceName: Имя файла, который анализируется.

Запуск действий

Основными причинами реализации посетителя узлов являются возможность документирования того, что обычно не документируется (например, вызовов функций, которые создают классы), или автоматическое генерирование документации для не документированного кода. Например, плагин может искать вызовы метода _trigger , так как знает, что это означает запуск события, а затем генерировать документацию для этого события.

Для запуска действий функция visitNode должна изменять свойства параметра события. В целом цель состоит в создании комментария и запуске события. После того, как парсер позволит всем посетителям узлов взглянуть на узел, он проверяет, есть ли у объекта события свойство comment и свойство event. Если оба свойства присутствуют, запускается событие, указанное в свойстве события. Обычно это событие symbolFound или jsdocCommentFound, но теоретически плагин мог бы определить свои собственные события и обработать их.

Как и в случае с плагинами обработчиков событий, плагин посетителя узлов может остановить работу последующих плагинов, установив свойство stopPropagation в объекте события (e.stopPropagation = true). Плагин может остановить запуск события, установив свойство preventDefault (e.preventDefault = true).

Отчёт об ошибках

Если вашему плагину нужно сообщить об ошибке, воспользуйтесь одним из следующих методов в модуле jsdoc/util/logger:

• logger.warn: Предупредить пользователя о возможной проблеме.
• logger.error: Сообщить об ошибке, от которой плагин может восстановиться.
• logger.fatal: Сообщить об ошибке, которая должна заставить JSDoc прекратить выполнение.

Использование этих методов создаёт более удобный пользовательский опыт, чем просто выброс ошибки.

Примечание: Не используйте модуль jsdoc/util/error для отчёта об ошибках. Этот модуль устарел и будет удалён в будущей версии JSDoc.

var logger = require('jsdoc/util/logger');

exports.handlers = {
    newDoclet: function(e) {
        // Your code here.

        if (somethingBadHappened) {
            logger.error('Oh, no, something bad happened!');
        }
    }
};