Генерация документации - какие ящики должны поставить галочку?

Question

Я обращаю внимание на то, что моя команда должна более тщательно документировать свой код для некоторых крупных будущих проектов и сделать жизнь немного менее болезненной, я ориентируюсь на генераторы документации XML, такие как Sandcastle , Doxygen или Box Live Documenter .

Какие ключевые моменты я должен учитывать при оценке наилучшего варианта и какой опыт привел вас к определенному решению?

Answer 1

Для меня ключевые соображения были бы:

1. Полностью автоматизирован: Может ли он быть настроен таким образом, чтобы в значительной степени никакой внешней работы не требуется создавать или редактировать документацию.

2. Полностью оформлено: Может ли документация полностью оформлена так что это выглядит великолепно в вики или PDF после того, как это сгенерировано. я должен быть возможность менять цвета, размеры шрифта, макеты и т. д.

3. Хорошая фильтрация: Могу ли я выбрать только те элементы, которыми я хочу быть генерироваться. Я должен быть в состоянии фильтровать пространства имен, типы файлов, классы и т. д.

4. Настройка: Могу ли я включить верхние и нижние колонтитулы, пользовательские элементы, и т.д.

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

1. Разработчик вносит изменения в код

2. Они обновляют теги документации прямо над кодом, который они только что изменили

3. нажимаем кнопку генерации

Затем Doxygen извлечет всю XML-документацию из кода, отфильтрует ее так, чтобы она включала только те классы и методы, которые мы хотим, и применим стиль CSS, который мы предварительно для него создали. Наш конечный результат - внутренняя вики, которая выглядит так, как мы хотим, и не требует редактирования.

Дополнительно: У нас есть все наши проекты в различных git-репозиториях. Мы переносим все это в одну корневую папку и генерируем документы из этой корневой папки ..

Было бы интересно узнать, как другие автоматизируют работу еще? ..

Answer 2

1. Кто платит за документацию и почему? (достаточно ли стабильна система, добавляет ли она достаточную ценность)
2. Кто будет читать это, и почему она не использует более эффективный канал связи? (если исправить в основном расстояние во времени / месте)
3. Кто будет держать это в курсе.
4. Когда вы собираетесь его уничтожить? (Автоматически, если он не был прочитан или обновлен за последние три месяца?)

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

[редактировать] Документация стоит времени и денег, чтобы написать и поддерживать в актуальном состоянии. Документация стиля JavaDoc оказывает серьезное пагубное влияние на объем одновременно видимого кода и может быть хорошей идеей для разработчиков, использующих код, но не для тех, кто его пишет.