Мой подход к документированию проектов на Javascript

В этой короткой статье я поделюсь с вами своим недавним опытом документирования кода JavaScript. Я пришел к довольно интересному решению с использованием JSDocs, которое может быть применено практически к любому javascript — приложению среднего размера.

Чтобы увидеть, то чем я говорю, вы можете посмотреть на: https://softwarebrothers.github.io/admin-bro-dev/index.html и связанный репозиторий GitHub: https://github.com/SoftwareBrothers/admin-bro-dev

Так что если у вас есть приложение, где:

• Фронтенд написан на React/Angular/Vue/Vanilla
• API написано на Node.js
• И у вас также есть пара (микро) сервисов, написанных на JavaScript …

…то эта статья для вас.

Я не буду рассказывать вам о том, как установить JSDoc в вашем проекте и что означает каждый тег JSDoc. Я скорее опишу идею верхнего уровня настройки JSDoc для полного документирования всего проекта. Вы всегда можете посетить мой канал на YouTube и посмотреть 2 эпизода о JSDocs и better-docs.

Но прежде чем мы углубимся в детали — давайте поговорим о: «зачем это нужно?

Какую проблему решает документирование — или зачем нам нужна документация?

Я участвую в нескольких ИТ-проектах уже десять лет, и всегда требовалась какая-то документация по нескольким причинам:

• Чтобы хранить и делиться «внутренней» информацией о системе, описания часто используемых терминов и т. д.
• Для описания архитектуры высокого уровня — какой сервис за что отвечает.
• Для описания деталей реализации низкого уровня — каковы цели данных Class/Module, описания их интерфейсов и объяснения того, как их использовать

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

6 Концепций

Концепция №. 1: Корневой репозитарий

Обычно «Архитектура приложения» и «Знание бизнеса (Business Knowledge)» — это термины, которые относятся ко всем службам в приложении. Вот почему мне нужно было одно место, где я мог бы разместить всю информацию, касающуюся этих 2 моментов.

Поскольку я использовал JSDocs, я собрал весь код в одном репо с помощью git submodule (https://git-scm.com/book/en/v2/Git-Tools-Submodules) — я буду называть его root repo.

Проще говоря, git submodules позволяют вам связывать одно хранилище с другим.

Это структура основной папки моего корневого хранилища:

(git submodule) /fronted
(git submodule) /api
(git submodule) /microservice1
(git submodule) /microservice2
/infrastructure
/docs-src
/docs
package.json
readme.md etc

В /infrastructure я храню все файлы, связанные с docker и docker-compose.

/docs-src содержит файлы, используемые JSDoc, не обязательно связанные с кодом, такие как статические файлы (изображения, screenshots) и учебные пособия (markdown).

/docs — это место, где хранится актуальная документация.

ОК — вот как я создал несколько репозиториев. Затем я установил JSDoc3 в корневом репозитории (поэтому там есть файл package.json)

Концепция № . 2: JSDOC

Теория:

JSDoc — это язык разметки, используемый для описания кода, написанного на javascript. Он выглядит примерно так:

/**
  * Finds one Record in the Resource by its id
  * @param  {String} id      uniq id of the Resource Record
  * @return {Promise<BaseRecord>}   record
  * @abstract
  */ async findOne(id) {
 //...
 }

В приведенном выше примере мы описали функцию findOne:

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

JSDoc3, с другой стороны, это инструмент, который считывает все комментарии JSDoc и генерирует из них HTML-документацию.

Мой подход:

Каждый репозиторий (включенный как submodule) имеет свои собственные комментарии JSDoc. JSDoc3 можно передать файл конфигурации, в котором я определил, что:

• вся документация должна быть генерируется в папку /docs
• JSDoc должен прочитать все git submodules
• место, куда я положу мои уроки, будет /docs-src (читайте следующий пункт)

…и кучу других параметров.

Концепция №. 3: учебники JSDOC

JSDoc сам по себе создает очень хорошую низкоуровневую документацию для классов, модулей и т. д. Но он также позволяет добавлять пользовательские файлы markdown — они называются «учебниками».

Вот почему я создал папку /docs-src в корневом репозитории — это место, где я размещаю файлы учебников.

Учебники очень полезны, когда речь идет о хранении «Бизнес-знаний». Там вы можете описать общую архитектуру, инструкции по установке, отношения между сервисами, моделями баз данных и т. д.

Взгляните на разделы учебников, которые я создал: https://softwarebrothers.github.io/admin-bro-dev

Концепция №. 4: Графики с MERMAID

Следующее, что я использовал, были графики, созданные с помощью Mermaid. По сути, вы можете добавить график в комментарии JSDocs с помощью тега @mermaid (доступно через плагин mermaid jsdoc).

Я также добавил несколько графиков в уроки со следующим хаком:

### Regular Markdown
Since markdown allows you to insert HTML, this is what you can do:
<div class="mermaid">
 graph LR
 A[BaseDatabase] -->|has many| B(BaseResource)
        B --> |has many|C(BaseRecord)
 B --> |has many|D(BaseProperty)
</div>

At the end of the file you also have to include mermaid:

<script src="https://cdn.rawgit.com/knsv/mermaid/7.0.0/dist/mermaid.min.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.rawgit.com/knsv/mermaid/7.0.0/dist/mermaid.css">
<script>mermaid.initialize({ startOnLoad: true });</script>

Концепция №. 5: Внешний вид документации

По умолчанию JSDoc3 генерирует документацию, которая выглядит следующим образом.

Я попытался найти хорошую тему, которую мог бы использовать (на странице JSDoc GitHub есть пара ссылок на разные шаблоны), но в конце концов я решил попросить одного из наших дизайнеров пользовательского интерфейса создать что-то очень простое, но очень удобное для пользователя. дружелюбный.

Наша тема называется better-docs и может быть найдена здесь: https://github.com/SoftwareBrothers/better-docs

И вот как выглядит та же самая документация:

Концепция №. 6: Группировка с помощью @CATEGORY

Когда я настроил JSDoc для анализа всех git submodules, у меня появилась «не очень хорошо организованная» документация (она была абсолютно запутанной). Поэтому я решил написать крошечный плагин JSDoc, который группирует вещи по категориям — он включен в ранее упомянутые better-doc.

Короче говоря, используя его, вы можете разделить документацию по категориям на боковой панели. Опять же — взгляните на https://softwarebrothers.github.io/admin-bro-dev/index.html — где Adapter, Decorators, Errors и PropertyTypes являются категориями.

И это была последняя из 6 концепций, которые я использовал. Все эти вещи не очень новаторские, но в сочетании они создают очень мощный набор инструментов для документации.

Развертывание

Существует несколько вариантов развертывания документации, сгенерированной JSDoc. Самые очевидные из них:

• Опубликуйте это в AWS S3 bucket и хост как статическую страницу
• Сгенерируйте документацию на каком нибудь вашем сервере и настройте Nginx/Apache для его размещения.
• Используйте GitHub (или BitBucket)

В прошлый раз я использовал третий вариант — поэтому я создал папку /docs внутри корневого репозитория для хранения документации. Вы можете настроить GitHub для использования в качестве источника публикации, и это стоит того чтобы проверить.

После того как вы сгенерировали документацию в исходном коде, помните, что вы должны время от времени обновлять ее. Подумайте о своих коллегах, которые получают PullRequests с 20 файлами обновленной HTML-документации — как минимум они будут разочарованы … :).

Наличие отдельного корневого репозитория для документации решает эту проблему — фиксации кода остаются внутри подмодулей, и PR, обновляющие сгенерированную документацию, отправляются в корневое репо.

Заключение

До сих пор я использовал эту структуру в 3 проектах, и она работает довольно хорошо.

Я, наверное, уже упоминал об этом пару раз, но вы можете увидеть рабочий пример здесь:

• Исходный код: https://github.com/SoftwareBrothers/admin-bro-dev
• Актуальная документация: https://softwarebrothers.github.io/admin-bro-dev/

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

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

Оригинальная статья: Wojciech Krysiak — MY APPROACH TO DOCUMENTING JAVASCRIPT PROJECTS