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

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


person Yes Man    schedule 17.03.2012    source источник


Ответы (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()
    {
    }
}
person Cody Gray    schedule 17.03.2012
comment
Итак, вы должны делать это для всего, для чего хотите добавить документацию? Методы, классы и т.д.? - person Yes Man; 17.03.2012
comment
Что ж... делать это следует только для больших разделов документации. В большинстве случаев я бы рекомендовал хранить код и документацию в одном файле. - person Rene Saarsoo; 19.03.2012
comment
Это очень полезно, если у вас есть две отдельные группы, управляющие кодом и документацией. В противном случае, да, вы, вероятно, должны просто держать их вместе. Это документация по коду, предназначенная для использования другими разработчиками, использующими ваши общедоступные API; не совсем то же самое, что и то, что стоит перед публикой. - person Cody Gray; 19.03.2012