Как Doc-Holiday упрощает проектную документацию на JavaScript/TypeScript.
Если у вас есть опыт работы с JavaScript, возможно, вы использовали JSDoc. Вы, вероятно, разочаровались в том, что «автоматическая» документация по API отображает разумные результаты из вашего хорошо написанного исходного кода.
Документация, которую вы получите в итоге, может показаться разумной по сравнению с запутанными результатами другой сгенерированной документации. Однако блоки комментариев вашего исходного кода теперь замусорены множеством символов «@».
Почему?
JSDoc был создан давным-давно, когда JavaScript был новым. В языке формально не существовало таких конструкций, как классы и перечисления или интерфейсы, примеси или определения типов. Однако эксперты по JavaScript нашли способы создавать эти конструкции из процедурной структуры JavaScript, использовавшейся в то время. Сегодня вы можете использовать ключевое слово «класс» для определения класса, но до появления ключевого слова «класс» концепция построения «класса» осуществлялась путем создания функций и добавления членов в прототип функции.
Конечно, это означало, что инструменту документирования нужно было сообщить, что функция обрабатывается как @class и что связанные объявления членов являются @memberof этого класса.
Теперь JSDoc распознает класс, объявленный с помощью ключевого слова class в коде, но некоторые другие понятия, такие как перечисления и определения типов, просто не имеют поддержки чистого языка JavaScript и должны создаваться в блоках комментариев исходного кода с использованием часто сбивающих с толку тегов JSDoc.
Я использую TypeScript уже некоторое время, и одна из замечательных особенностей TypeScript — это его типы. Если я напишу функцию и объявлю типы для таких параметров, как:
function Foo(bar:string, baz:number) {
}
Почему я должен был также включать объявления @param в свой комментарий к функции, чтобы задокументировать их?
JSDoc плохо работает с TypeScript. Он не будет обрабатывать файл .ts напрямую. Однако, поскольку комментарии передаются из исходного кода ts, вы можете запускать jsdoc для файлов .js, созданных компилятором TypeScript. Это работает, но имеет недостатки. Вам по-прежнему необходимо включать теги @param и @return в свои функциональные блоки, а структура классов не идеальна. Это требует избыточности для сбора документации для любого типа определений или перечислений.
Представляем Док-Холидей
Doc-Holiday — это бесплатный проект с открытым исходным кодом, доступный для загрузки с NPM, который стремится облегчить эти разочарования.
Вы можете найти его на npm в разделе @tremho/doc-holiday.
Он работает иначе, чем другие механизмы документирования, совместимые с JSDoc, — это не механизм рендеринга HTML/Markdown. Вместо этого это посредник, который создает разумные заглушки исходного кода, готовые к JSDoc, из файлов TypeScript или JavaScript, а затем вызывает механизм рендеринга по вашему выбору, чтобы преобразовать его в HTML или Markdown для публикации.
Вы получаете полную поддержку сообщества JSDoc в том, как выглядит ваш вывод, используя широкий выбор профессионально выглядящих шаблонов и тем. Кроме того, вы можете избежать ловушек, связанных с необходимостью добавления явных тегов JSDoc в избыточном пересказе кода, который вы уже определили.
Doc-Holiday позволяет вам использовать jsdoc, jsdoc2md или документацию JS для вашего механизма рендеринга JSDoc.
документация JS начинается с той же философии, что и Doc-Holiday. Это упрощает использование JSDoc, делая дополнительные выводы из исходного кода, а также уменьшая и нормализуя большое количество тегов JSDoc до разумно управляемого количества. Он также обеспечивает чистый и согласованный вывод документации как для HTML, так и для Markdown.
Однако документация JS не поддерживает TypeScript и, следовательно, не имеет простой поддержки таких вещей, как свойства классов, интерфейсы, определения типов или перечисления.
Doc-Holiday разработан с учетом TypeScript с самого начала, хотя он также хорошо справляется с традиционным JavaScript. Он распознает ряд шаблонов, которые могут установить объект кода и его документируемые свойства, и переводит их в блоки, совместимые с JSDoc, во время обработки документа, поэтому вам не нужно этого делать. Ваш исходный код может оставаться относительно чистым и читаемым.
Док-Холидей имеет и другие интересные особенности:
- Возможность документировать внутренний класс
- Возможность документировать определения пользовательских типов и обратные вызовы
- Способность распознавать и документировать примеси и интерфейсы
- Вводит ограничения — спецификации диапазонов значений для значений всех типов, которые документируют, как выглядят допустимые значения, и могут применяться во время выполнения.
- Диаграммы PlantUML — поддержка любых директив языка диаграмм Plant UML для создания красивых и информативных диаграмм из комментариев к коду.
- Поддерживает публикацию связанной документации в дополнение к документам API, сгенерированным исходным кодом.
- Doc-Holiday — это одновременно инструмент командной строки и модуль Node.js, предоставляющий программный API, который можно использовать в настраиваемых конвейерах документации.
В общем, Док-Холидей — долгожданный перерыв после перестрелки, которая была раньше.
Раскрытие информации: Стивен Омерт является автором @tremho/doc-holiday
Дополнительные материалы на PlainEnglish.io. Подпишитесь на нашу бесплатную еженедельную рассылку новостей. Подпишитесь на нас в Twitter и LinkedIn. Присоединяйтесь к нашему сообществу Discord.
