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

<p>по сути, вопрос заключается в следующем:<em> где (и в каком формате) я должен хранить текстовую документацию для разработчиков, связанную с моими проектами visual studio? </em></p><p>чтобы уточнить: комментарии xml хороши, но они не охватывают все варианты использования. иногда вы хотите описать архитектуру классов проекта на высоком уровне, добавить примечания по использованию в вашу библиотеку или просто оставить любое другое сообщение для будущих поколений разработчиков, работающих над этим проектом.</p><p>я хотел бы добавить эти документы непосредственно в виде файлов в проект visual studio, чтобы (а) они были доступны разработчику без дальнейшего поиска, и (б) они контролировались версиями (используя тот же репозиторий svn/git/what) в качестве исходного кода).</p><p>в настоящее время я добавляю папку <code>\_documentation</code> в проект и использую текстовые файлы, но я не уверен, что это лучшее решение. visual studio не имеет опции для автоматического переноса текста<sup>1</sup>и ручная фиксация разрывов строк после каждого изменения раздражает. с другой стороны, документы word плохо работают с контролем версий, а tex слишком сложен для настройки и обучения на каждом пк разработчика.</p><p>существует ли устоявшаяся лучшая практика для этого?</p><hr><p><sup>1</sup> я знаю, что есть edit/advanced/word-wrap, но это влияет только на отображение, а не на сам файл.</p>

<p>у меня просто была такая же проблема - только я заметил, что смог добавить html-файл. после открытия просто переключитесь на «дизайн» в нижней части экрана . вы можете изменить<em> build action </em>с «контент» на «нет»</p><p>поскольку это жестко закодированный документ html, также можно использовать встроенные изображения (например, схему)</p><p>также для моих целей (руководство по программированию, описание архитектуры. примеры использования базы данных) я решил создать отдельный проект (<code>\_documentation</code>) в качестве<em> windows forms </em>, так как это позволит мне (или новому программисту) иметь работающий пример ,.</p>

<p>я использую ghostdoc (дополнение к visual studio) для документации моего проекта, так как я добавляю классы, методы, свойства и т. д .: <a href="http://visualstudiogallery.msdn.microsoft.com/46a20578-f0d5-4b1e-b55d-f001a6345748">http://visualstudiogallery.msdn.microsoft.com/46a20578-f0d5-4b1e-b55d-f001a6345748</a> </p>

<p>у вас есть возможность, в комментариях xml, включить много данных, которые затем вы можете получить с помощью такого инструмента, как sandcastle <a href="http://sandcastle.codeplex.com/">(site)</a> , и превратить его в реальный справочный сайт в стиле msdn.</p><p>я склонен использовать этот метод и просто писать длинные xml-комментарии <a href="http://msdn.microsoft.com/en-us/library/5ast78ax.aspx">(теги комментариев msdn)</a> (где это уместно), используя <code><para></para></code>, чтобы генерировать абзацы и объяснять любые шаблоны, коммерческие причины или архитектурную информацию, необходимые для будущих модификаторов/разработчиков. я также использую это, чтобы дать примеры использования.</p><p>хорошая партия тестов (хорошо написанных и названных) также может осветить цель кода, выступая в качестве спецификации.</p><p>я надеюсь, что это может быть немного информативным в вашем исследовании :)</p>

<p>комментарии xml лучше всего подходят для документирования конкретного метода и не идеальны для написания длинного концептуального контента. длинные комментарии xml могут отрицательно повлиять на читабельность кода.</p><p>мне понравилась функция документирования концептуальных тем в sandcastle, мы можем создавать и хранить концептуальную документацию, связанную с функциональностью или архитектурой, и объединять ее с документацией по коду (комментарии xml). разметки, которые вы можете использовать при написании концептуальных тем, являются расширяемыми, что означает, что мы можем даже придерживаться корпоративных шаблонов.</p>