Есть проект на 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?
Для тегов наподобие <see cref="...">
вам нужно использовать {}
-синтаксис, он не зависит от языка (C#/VB/...) и распознаётся парсером документации.
/// <summary>
/// Uses class <see cref="Range{T}"/>
/// </summary>
Для примеров кода лучше всего, вероятно, использовать блок CDATA:
/// <example>
/// <code>
/// <![CDATA[
/// new Test<T>(new Range<T>().Go());
/// ]]>
/// </code>
/// </example>
Кофе для программистов: как напиток влияет на продуктивность кодеров?
Рекламные вывески: как привлечь внимание и увеличить продажи
Стратегії та тренди в SMM - Технології, що формують майбутнє сьогодні
Выделенный сервер, что это, для чего нужен и какие характеристики важны?
Современные решения для бизнеса: как облачные и виртуальные технологии меняют рынок
Есть датагрид со столбцом, состоящим из комбобокса :
Коллеги, здравствуйте! Имею вот такой кодИдет постоянная утечка памяти, поскольку через данное соединение передаются jpeg'ги
Всем приветПодскажите как правильно установить ember-cli-pagination, что бы он работал
Друзья, портирую расширение из Chrome на FirefoxУ FF много своих особенностей с которыми нужно как то найти общий язык