Отдельная документация от кода

Question

Я не знаю, возможно ли это, но мне интересно, есть ли способ сохранить код и документацию в отдельных файлах, но все равно работать так же, как это обычно происходит со встроенной документацией.

Answer 1

Да, вы можете хранить комментарии документации XML во внешних файлах и включать их в файлы кода с помощью тега <include>.

С документации MSDN :

Тег позволяет вам ссылаться на комментарии в другом файле, которые описывают типы и элементы в вашем исходном коде.Это альтернатива размещению комментариев к документации непосредственно в файле исходного кода.Поместив документацию в отдельный файл, вы можете применять исходный контроль к документации отдельно от исходного кода.Один человек может получить файл исходного кода извлеченным, а кто-то другой может получить файл документации извлеченным.

Например, у вас может быть файл с именем 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()
    {
    }
}