Программисты всегда пользовались генераторами документации, когда это было возможно. Это упрощает документирование, позволяет получить справку по продукту без обращения к коду самого проекта. В Программе долгое время использовался JavaDoc, т.к. большинство проектов написаны на Java, но это было до недавнего времени. Сейчас проекты развиваются - мало кто представляет хороший продукт без хорошего UI. Отрасль frontend дала жизнь новому направлению разработки — разработчик UI. Концентрируясь на удобстве пользователя, а не на бизнес-процессах, UI-разработка позволяет избегать сложности бизнес-приложений — камень преткновения многих enterprise-решений.
Долгое время в этой сфере не было достойных инструментов, поскольку сложно подвергнуть автоматизации то, что не систематизировано. Со временем, появился инструмент, аналогичный JavaDoc, который даже получил схожее название — JSDoc. К его ключевым недостаткам можно отнести то, что он заставлял писать код определенным образом, что не всегда подходит для конкретного проекта. Стоит отметить, что код раздувался из-за обилия комментариев, что снижало читабельность самого кода для команды разработки.
Все изменилось в UI-разработке с приходом React. Все интерфейсы стали делиться на атомарные кусочки, из которых стали собираться огромные приложения: каждый кусок изолирован и покрыт необходимыми тестами. Каждая компания имеет свою собственную библиотеку UI компонентов, которые среди разработчиков еще называют UIKit.
В программе «Единая фронтальная система» мы разработали свою библиотеку, однако, и ее необходимо было документировать.
Мы начали писать документацию, но быстро пришли к пониманию того, что готовить ее вручную очень трудозатратно. Мы теряем драгоценное время на документировании, при этом отстаём в развитии самого проекта. Родилась идея генерировать документацию прямо из кода, идея не нова, но мы решились попробовать. У нас был проект на React и TypeScript. Используя слабо документированные возможности TypeScript, мы начали делать свою генерацию для каждого компонента. Все комментарии к каждому свойству компонента становились кусочками той документации, которая выводилась.
Мы не стали погружаться глубоко в корни TypeScript — это заняло бы слишком много времени. Использовав typedoc, получили структуру проекта в виде json, по этой структуре мы зеркально выстраиваем проект, но уже зная описания самих компонентов. Для удобной подгрузки описаний в саму документацию, мы реализовали особый компонент, который из зеркалированной структуры «вытягивает» описание и отображает его на странице. Звучит сложно, но на практике это работает как часы.
Дальше – больше. Нам не хотелось копировать код, чтобы вывести пример в документации и отобразить текст кода, на котором он был написан. Мы сделали отдельный компонент, который выводил и пример и код этого примера. Используя зеркалированную структуру, нам удалось достичь связи примеров с их исходным кодом.
Мы разместили решение на крупнейшем портале совместной разработки GitHub, чтобы вы могли использовать наш инструмент в своей ежедневной работе. Будем рады пообщаться в комментариях к посту.
Мы продолжаем работать над усовершенствованием решения, а именно:
У Java разработчиков есть JavaDoc, а что есть у разработчиков UI?
Долгое время в этой сфере не было достойных инструментов, поскольку сложно подвергнуть автоматизации то, что не систематизировано. Со временем, появился инструмент, аналогичный JavaDoc, который даже получил схожее название — JSDoc. К его ключевым недостаткам можно отнести то, что он заставлял писать код определенным образом, что не всегда подходит для конкретного проекта. Стоит отметить, что код раздувался из-за обилия комментариев, что снижало читабельность самого кода для команды разработки.
Все изменилось в UI-разработке с приходом React. Все интерфейсы стали делиться на атомарные кусочки, из которых стали собираться огромные приложения: каждый кусок изолирован и покрыт необходимыми тестами. Каждая компания имеет свою собственную библиотеку UI компонентов, которые среди разработчиков еще называют UIKit.
В программе «Единая фронтальная система» мы разработали свою библиотеку, однако, и ее необходимо было документировать.
Мы начали писать документацию, но быстро пришли к пониманию того, что готовить ее вручную очень трудозатратно. Мы теряем драгоценное время на документировании, при этом отстаём в развитии самого проекта. Родилась идея генерировать документацию прямо из кода, идея не нова, но мы решились попробовать. У нас был проект на React и TypeScript. Используя слабо документированные возможности TypeScript, мы начали делать свою генерацию для каждого компонента. Все комментарии к каждому свойству компонента становились кусочками той документации, которая выводилась.
Как этого удалось достичь?
Мы не стали погружаться глубоко в корни TypeScript — это заняло бы слишком много времени. Использовав typedoc, получили структуру проекта в виде json, по этой структуре мы зеркально выстраиваем проект, но уже зная описания самих компонентов. Для удобной подгрузки описаний в саму документацию, мы реализовали особый компонент, который из зеркалированной структуры «вытягивает» описание и отображает его на странице. Звучит сложно, но на практике это работает как часы.
Дальше – больше. Нам не хотелось копировать код, чтобы вывести пример в документации и отобразить текст кода, на котором он был написан. Мы сделали отдельный компонент, который выводил и пример и код этого примера. Используя зеркалированную структуру, нам удалось достичь связи примеров с их исходным кодом.
Мы разместили решение на крупнейшем портале совместной разработки GitHub, чтобы вы могли использовать наш инструмент в своей ежедневной работе. Будем рады пообщаться в комментариях к посту.
Мы продолжаем работать над усовершенствованием решения, а именно:
- Созданием live reloading: больше не нужно будет ждать пересборки всей библиотеки, чтобы увидеть результат в документации.
- Поддержкой JavaScript: мы понимаем, что сейчас многие проекты не используют TypeScript в своих проектах.
- Обновлением дизайна: сейчас инструмент выглядит аскетично, но это наши первые шаги в open source, обещаем, мы исправимся!