Я не знаю, возможно ли это, но мне интересно, есть ли способ сохранить код и документацию в отдельных файлах, но при этом работать так же, как обычно со встроенной документацией.
Отделяйте документацию от кода
Ответы (1)
Да, вы можете хранить комментарии XML-документации во внешних файлах и включать их в файлы кода с помощью тега <include>
.
Тег позволяет ссылаться на комментарии в другом файле, описывающие типы и элементы в исходном коде. Это альтернатива размещению комментариев к документации непосредственно в файле исходного кода. Поместив документацию в отдельный файл, вы можете применять систему управления версиями к документации отдельно от исходного кода. Один человек может получить файл исходного кода, а другой — файл документации.
Например, у вас может быть файл с именем xml_include_tag.doc
, содержащий следующие комментарии к документации:
<MyDocs>
<MyMembers name="test">
<summary>
The summary for this type.
</summary>
</MyMembers>
<MyMembers name="test2">
<summary>
The summary for this other type.
</summary>
</MyMembers>
</MyDocs>
И вы должны включить эту документацию в свой файл кода следующим образом:
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
static void Main()
{
}
}
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
public void Test()
{
}
}
person
Cody Gray
schedule
17.03.2012
Итак, вы должны делать это для всего, для чего хотите добавить документацию? Методы, классы и т.д.?
- person Yes Man; 17.03.2012
Что ж... делать это следует только для больших разделов документации. В большинстве случаев я бы рекомендовал хранить код и документацию в одном файле.
- person Rene Saarsoo; 19.03.2012
Это очень полезно, если у вас есть две отдельные группы, управляющие кодом и документацией. В противном случае, да, вы, вероятно, должны просто держать их вместе. Это документация по коду, предназначенная для использования другими разработчиками, использующими ваши общедоступные API; не совсем то же самое, что и то, что стоит перед публикой.
- person Cody Gray; 19.03.2012