Страницы

Поиск по вопросам

четверг, 11 октября 2018 г.

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

Есть проект на 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?


Ответ

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

/// Uses class ///
Для примеров кода лучше всего, вероятно, использовать блок CDATA:
/// /// /// (new Range().Go()); /// ]]> /// ///

Комментариев нет:

Отправить комментарий