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

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

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

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

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

Есть ли у вас хорошо зарекомендовавшая себя практика?

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

Ответы

Ответ 1

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

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

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

Ответ 3

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

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

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

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

Ответ 4

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

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