Моя команда использует ESDoc для генерации документации JS проектов. Мы используем кастомные плагины, чтобы сгенерированные документы соответствовали нашим потребностям. В этом посте я расскажу о некоторых наших плагинах, чтобы показать, что вывод ESDoc можно легко настроить.
Чтобы следовать примерам, лучше всего заранее знать, как работают плагины ESDoc. Я написал пост об этом, но вы можете пропустить его и перейти к примерам, если чувствуете себя достаточно уверенно.
Импорт из корневого пакета
ESDoc сгенерирует рекомендуемую строку импорта для метода, используя полный путь:
import {sum} from "awesome-math/src/sum.js";В нашем коде мы предпочитаем реэкспортировать все из основной точки входа, чтобы избежать проблем с будущими рефакторингами, поэтому мы рекомендуем использовать:
import {sum} from ‘awesome-math’ Мы можем исправить вывод ESDOC, создав специальный плагин, который использует обработчик onHandleDocs для перезаписи importPath переменных, функций и классов.
Замаскируйте переменную как функцию
ESDoc выводит документацию с использованием кода AST. Функциями считаются только выражения и объявления функций. Это не будет хорошо работать, когда функции обертываются функциями высокого порядка, такими как карри.
Чтобы решить эту проблему, мы используем специальный тег: function, чтобы отметить код.
На шаге onHandleDocs ищем тег. Если присутствует, запись документа устанавливается в kind function, эффективно обманывая ESDoc. Обратите внимание, что неподдерживаемые теги можно найти в массиве doc.unknown.
Внедрение ссылок
Полезно связывать внешние источники с документацией, но утомительно писать полные URL-адреса каждый раз, когда мы добавляем новую ссылку. Чтобы упростить это, мы используем плагин для вставки ссылок из таблицы в комментарии к коду.
Мы получаем таблицу через config в обработчике onStart, чтобы изменить комментарии ESDoc каждого исходного файла, используя простую замену текста в onHandleCode.
Примеры внедрения кода
Иногда и в комментариях к коду, и в руководствах используются одни и те же примеры. Внедряя эти примеры с помощью плагина, мы можем делиться фрагментами кода. Также мы можем рассматривать их как нормальный код, чтобы их можно было наклеить, предопределить и даже выполнить.
Мы добавляем примеры в исходный код, заменяя текст в комментариях к коду, как мы это делали в предыдущем плагине. Для работы с учебными файлами мы используем onHandleDocs и заменяем текст в файлах уценки. Мы украшаем внедренные примеры комментариями в исходных файлах и ограничениями кода в уценках учебника.
Попался: зависимости
У плагина примеров есть небольшая проблема. Если вы попробуете, то заметите, что он не работает с обучающими программами. Проблема тонкая. Учебные файлы создаются во время выполнения с помощью esdoc-integration-manual-plugin (включенного в esdoc-standard-plugin). Наш плагин зависит от esdoc-integration-manual-plugin, но, в зависимости от порядка выполнения, он может быть выполнен раньше. Чтобы обеспечить правильный порядок, мы используем другой плагин.
Используя onHandlePlugins, можно изменить порядок коллекции подключаемых модулей, чтобы наши настраиваемые подключаемые модули выполнялись после модулей ESDoc. Магия!
Добавление разметки в макет: Google Analytics
Иногда необходимо изменить разметку, созданную ESDoc. Например, добавление дополнительной разметки, удаление ненужных фрагментов, изменение текстов, перевод и т. Д. В этом случае мы хотим отслеживать некоторые общедоступные документы с помощью кода отслеживания Google Analytics.
С помощью обработчика onHandleContent мы можем изменить тег head и добавить фрагмент отслеживания Google Analytics. Код отслеживания будет передан как опция плагина.
В этом примере мы использовали простую замену текста, но я рекомендую вам использовать некоторую библиотеку, например cheerio, если вы собираетесь сильно изменить HTML.
Архивирование документов
Иногда мы распространяем нашу документацию в виде zip-пакета. Вместо того, чтобы использовать собственный сценарий npm, мы можем использовать плагин, чтобы позволить ESDoc обрабатывать архивирование после создания всей документации.
Мы используем обработчик onComplete для этой задачи и полагаемся на библиотеку архиватора для сжатия. Имя ZIP-файла определяется с помощью ключей package.json name и version.
Попался: ваш плагин не работает
Если вы поиграете с приведенными выше примерами или напишете свои собственные плагины, вы можете столкнуться с этой ошибкой:
../esdoc-plugins-example/node_modules/esdoc/out/src/Util/InvalidCodeLogger.js:72 const start = Math.max(error.loc.line — 3, 1); TypeError: Cannot read property ‘line’ of undefined
Не отчаивайтесь, ваш плагин сломан. У вас просто синтаксическая ошибка или ошибка времени выполнения. ESDoc имеет некоторые ошибки и не может вывести, где находится ошибка.
Подвести итог
Примеры, показанные в этом посте, могут быть адаптированы под ваши нужды. К большинству из них можно подойти по-другому и реализовать с помощью других этапов жизненного цикла. Просто попробуйте что-то новое и посмотрите, что получится. Приложив некоторые усилия, можно настроить вывод ESDoc и избежать большинства его недостатков.
