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