Есть проект на c# с подробной документацией в xml, вот пример документации:
/// ... - много-много текста
/// <example>
/// Классический пример использования:
/// <code>
///
/// public delegate void MyDelegateMethod(int value);
/// ...
///
/// Type type = assembly.GetType("Data.Test");
/// MyDelegateMethod fooMethod = type.GetMethod<MyDelegateMethod>("Foo");
/// fooMethod.Invoke(42);
///
/// </code>
/// </example>
public static T GetMethod<T>(this Type type, string name) where T : class {
return GetMethod<T>(type,name,true);
}
Далее, есть VisualStudio нескольких версий - 2012 и 2015. Так вот, с точки зрения XML данные доки ошибочны, так как генерик-метод:
type.GetMethod<MyDelegateMethod>("Foo");
интерпретируется как открытие тега MyDelegateMethod, который, не закрывается.
Скрин из MS Visual Studio 2012, при попытке прочитать документацию всплывающим контекстом:
С точки зрения документации - всё чисто (код написан в ограничивающих тегах <code> </code>).
В поисках истины, прочитал я рекомендации с англоязычных ресурсов:
Но, всё это сделает код внутри тегов <code> не рабочим. (Что это значит - найдётся горе-программист, который скопирует код из этой документации и искренне удивится что без редактирования этот код не работает ни под одним из существующих шарпов) Кроме того, код вида:
MyDelegateMethod fooMethod = type.GetMethod<MyDelegateMethod>("Foo");
воспринимается сразу, и без серьёзных рассуждений, в свою очередь, код такого вида:
MyDelegateMethod fooMethod = type.GetMethod<MyDelegateMethod>("Foo");
сходу сложно определить.
Подскажите, как лучше вести документацию подобного рода, и каким образом сделать код одновременно и читаемым, и логичным с точки зрения xml?