Документация (summary) во внешнем файле

295

28 марта 2017, 10:34

Имеется библиотека. В ней методы, поля (свойства), которые хорошо бы описать, чтобы при использовании Visual Studio высвечивала описание и подсказки для того или иного поля/метода.

Я знаю, что можно писать <summary> прямо в коде и в свойствах сборки добавить галочку для создания XML-документации.

Но если я сейчас прямо в коде начну писать описание, то код заметно удлинится. Можно ли как-то в отдельном файле написать эту документацию?

Чтобы в коде не было <summary>, но IntelliSense смог отображать эту информацию?

Answer 1

Да, это возможно. Используйте тег include. Теперь достаточно

Аннотировать нужный метод так:

/// <include file='external_summary.xml' path='docs/method[@name="MethodName"]/*' />
public void MethodName(string arg)
{
}

Создать файл external_summary.xml, имеющий такую структуру:

<docs>
    <method name="MethodName">
        <summary>Описание метода</summary>
        <param name="arg">Описание параметра arg</param>
    </method>
</docs>

В результате после компиляции сборки с опцией /doc вы получите следующую xml-документацию:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Application</name>
    </assembly>
    <members>
        <member name="M:Application.Program.MethodName(System.String)">
            <summary>Описание метода</summary>
            <param name="arg">Описание параметра arg</param>
        </member>
    </members>
</doc>