Документация - всегда скучная задача для разработчиков, пишущих программное обеспечение. Когда нам приходится писать документацию для других разработчиков, это в большинстве случаев вызывает разочарование, и мы предпочитаем программировать.
Я работаю во французской компании, предоставляющей ИТ-услуги, и мы должны предоставить такую документацию нашим клиентам. Обычно мы имеем дело с двумя сценариями:
- Документация, написанная с использованием Microsoft Word, имеет «функциональный» вид, а иногда и API внутри. Целями являются люди, которые не являются разработчиками, а являются менеджерами.
- Сгенерированная документация, например документация по API, для внутреннего и / или внешнего программного обеспечения.
Поскольку мы разработчики, мы по своей природе «ленивые» люди, которые большую часть времени стараемся кодировать задачу, а не выполнять ее. И «сгенерированная» документация - хорошее решение.
Другое преимущество - «живая» документация. По мере роста программного обеспечения и документирования кода документация автоматически синхронизируется с последними обновлениями.
Для разработчиков AngularJS де-факто решением для создания документации является инструмент под названием Dgeni, созданный командой AngularJS. Это инструмент очень низкого уровня, и он отлично работает с небольшой настройкой и парой скриптов.
Несколько месяцев назад мы начали переход на Angular в моей компании, и вопрос об инструментах «Документация» возник ровно в прошлом месяце.
После некоторых исследований в Интернете я обнаружил, что доступных инструментов не было, поэтому вывод был однозначным: «Давайте запрограммируем один».
Это был старт проекта Комподок.
Что такое Compodoc?
Compodoc - это инструмент для документирования вашего приложения на Angular.
Цель инструмента - создать документацию для всех распространенных API-интерфейсов Angular: модулей, компонентов, инъекций, маршрутов, директив, каналов и классических классов.
Приведите мне пример
Рабочий процесс прост. Я использую этот демонстрационный проект Angular для скриншотов ниже:
- установите его с помощью npm:
npm i -g @compodoc/compodoc
- запустите его в папке вашего приложения Angular 2
compodoc -p src/tsconfig.json
После нескольких журналов в консоли вы получили сгенерированную документацию в папке ./documentation/ в корне папки вашего проекта.
Затем вы можете запустить HTTP-сервер в этой папке или запустить предыдущую команду с флагом -s, и инструмент предоставит вам документацию по умолчанию на http: // localhost: 8080
Домашняя страница создается с использованием файла README.md, если он обнаружен, а вместо страницы обзора.
На странице обзора используется отличный графический инструмент, разработанный Вассимом Чегамом под названием angular2-dependencies-graph; и дайте краткий обзор того, сколько модулей и компонентов у вас есть в вашем приложении.
Теперь давайте посмотрим на страницу одного модуля, например, TodoModule. У вас будет график локальных зависимостей для этого, а также список объявлений, импорта, экспорта и т. Д. Вашего модуля.
Давайте пойдем еще дальше со страницей компонентов, HeaderComponent. Как и на странице модуля, у вас есть все параметры декоратора «@component», если они доступны для этого компонента. Также доступны @inputs и @outputs.
То же самое для классов, директив, каналов и сервисов. TodoStore - хороший пример:
Какие комментарии мне нужно было написать, чтобы получить эти результаты?
Просто нормальные комментарии. Мы добавили поддержку синтаксиса уценки в пакете npm под названием отмечены. Мы думаем о возможности связывать комментарии, как обычные ссылки для уценки. Будьте на связи.
Что дальше ?
Этому инструменту всего несколько дней, поэтому мы постараемся протестировать его на как можно большем количестве проектов, чтобы улучшить и оптимизировать.
Мы планируем добавить возможность предоставления внешней «функциональной документации», такой как файлы уценки в папке, и добавить их в сгенерированную документацию в специальной записи в левой строке меню.
Мы также попытаемся сделать то же самое для проектов AngularJS 1.5+, построенных с использованием Typescript.
Мы ценим ваши отзывы. Пожалуйста, открывайте любую проблему, с которой вы можете столкнуться, и запросы на включение более чем приветствуются.
Следите за обновлениями Винсента Оглоблинского / @vogloblinsky.
