it-swarm.xyz

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

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

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

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

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

Существует ли устоявшаяся лучшая практика для этого?


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

40
Heinzi

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

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

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

8
aliceraunsbaek

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

3
ianaldo21

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

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

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

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

2
user1105802

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

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

0
ideafountain