XML документация кода с generics

#c_sharp #документация

Есть проект на c# с подробной документацией в xml, вот пример документации:

    /// ... - много-много текста
    /// 
    /// Классический пример использования:
    /// 
    ///     
    ///     public delegate void MyDelegateMethod(int value);
    ///     ...
    ///     
    ///     Type type = assembly.GetType("Data.Test");
    ///     MyDelegateMethod fooMethod = type.GetMethod("Foo");
    ///     fooMethod.Invoke(42);
    ///     
    /// 
    /// 
    public static T GetMethod(this Type type, string name) where T : class {
        return GetMethod(type,name,true);
    }


Далее, есть VisualStudio нескольких версий - 2012 и 2015. Так вот, с точки зрения
XML данные доки ошибочны, так как генерик-метод:

type.GetMethod("Foo");


интерпретируется как открытие тега MyDelegateMethod, который, не закрывается.

Скрин из MS Visual Studio 2012, при попытке прочитать документацию всплывающим контекстом:


С точки зрения документации - всё чисто (код написан в ограничивающих тегах 
).

В поисках истины, прочитал я рекомендации с англоязычных ресурсов:


Замена символов '<' и '>' на < и >
Замена символов '<' и '>' внутри генерик на '{' и '}'


Но, всё это сделает код внутри тегов  не рабочим. (Что это значит - найдётся
горе-программист, который скопирует код из этой документации и искренне удивится что
без редактирования этот код не работает ни под одним из существующих шарпов) Кроме
того, код вида:

MyDelegateMethod fooMethod = type.GetMethod("Foo");


воспринимается сразу, и без серьёзных рассуждений, в свою очередь, код такого вида:

MyDelegateMethod fooMethod = type.GetMethod<MyDelegateMethod>("Foo");


сходу сложно определить.

Подскажите, как лучше вести документацию подобного рода, и каким образом сделать
код одновременно и читаемым, и логичным с точки зрения xml?
    

Ответы

Ответ 1

Для тегов наподобие  вам нужно использовать {}-синтаксис, он не зависит
от языка (C#/VB/...) и распознаётся парсером документации.

/// 

/// Uses class 
/// 


Для примеров кода лучше всего, вероятно, использовать блок CDATA:

/// 
/// 
/// (new Range().Go());
/// ]]>
/// 
///