Лучший способ добавить документацию разработчика к проектам Visual Studio

Question

В основном, вопрос: Где (и в каком формате) хранить текстовую документацию разработчика, связанную с моими проектами Visual Studio?

Чтобы уточнить: комментарии XML замечательные, но они не охватывают все варианты использования. Иногда вы хотели бы описать архитектуру класса проекта на высоком уровне, добавить примечания к использованию в свою библиотеку или просто оставить любые другие сообщения для будущих поколений разработчиков, работающих над этим проектом.

Я хотел бы добавить эти документы непосредственно в виде файлов в проект Visual Studio, чтобы (а) они были доступны разработчику без дальнейшего поиска и (б) они контролируются версией (с использованием того же svn/git/любой репозиторий в качестве исходного кода).

В настоящее время я добавляю в проект папку _Documentation и использую текстовые файлы, но я не уверен, что это лучшее решение. Visual Studio не имеет возможности для автоматического текстового обтекания текста , а вручную исправление разрывов строк после каждого изменения раздражает. С другой стороны, документы Word не очень хорошо работают с управлением версиями, и TeX слишком много хлопот для настройки и обучения на каждом компьютере разработчика.

Есть ли устоявшаяся передовая практика для этого?

---

Я знаю, что есть Edit/Advanced/Word-Wrap, но это влияет только на отображение, а не сам файл.

Answer 1

У меня была такая же проблема - только я заметил, что мне удалось добавить HTML-файл. После открытия просто переключитесь на «Дизайн» в нижней части экрана. Вы можете изменить Build Action от «Содержание» на «Нет»

Как это жестко закодированы HTML документа, также можно использовать встроенные рисунки (например, диаграмма)

Также для моей цели (руководство по программированию, описание архитектуры. примеры использования базы данных). Я решил создать отдельный проект (_Documentation) как Windows Forms, так как это позволит мне (или новому программисту) запустить пример.

Answer 2

Я использую GhostDoc (Visual Studio дополнения) для документирования моего проекта, как я добавляю классы, методы, свойства и т.д.: http://visualstudiogallery.msdn.microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748

Answer 3

У вас есть возможность, в комментариях XML, чтобы включить много данных, вы можете взять с помощью инструмента, такого как Sandcastle (site), и превратиться в реальный сайт ссылки в стиле MSDN.

Я использую этот метод и просто пишу длинный XML-комментарий (MSDN comment tags) (при необходимости), используя <para></para>, чтобы генерировать абзацы и объяснять любые шаблоны, бизнес-причины или архитектурную информацию, необходимую будущим модификаторам/разработчикам. Я также использую его для использования примеров использования.

Хорошая серия тестов (хорошо написанная и названная) также может действительно осветить цель кода, действуя как спецификация.

Я надеюсь, что может быть немного информативно в ваших исследованиях :)

Answer 4

XML Комментарии лучше всего подходит для документирования конкретного метода и не подходит для написания долго концептуального содержания. Длинные комментарии XML могут негативно повлиять на читаемость кода.

Мне понравилась функция «Концептуальная тема документации» Sandcastle, мы можем создавать и хранить концептуальную документацию, связанную с функциональностью или архитектурой, и объединить ее с документацией по коду (комментарии XML). Разметки, которые вы можете использовать при написании концептуальных тем, можно продлить, что означает, что мы можем даже придерживаться шаблонов Enterprise.