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

201
11 июля 2017, 18:29

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

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

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

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

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

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

MyDelegateMethod fooMethod = type.GetMethod&lt;MyDelegateMethod&gt;("Foo");

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

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

Answer 1

Для тегов наподобие <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>
READ ALSO
DataGridTemplateColumn с вложенным ComboBox не срабатывает команда

DataGridTemplateColumn с вложенным ComboBox не срабатывает команда

Есть датагрид со столбцом, состоящим из комбобокса :

259
Утечка памяти, как бороться C#

Утечка памяти, как бороться C#

Коллеги, здравствуйте! Имею вот такой кодИдет постоянная утечка памяти, поскольку через данное соединение передаются jpeg'ги

231
ember cli pagination как должен работать

ember cli pagination как должен работать

Всем приветПодскажите как правильно установить ember-cli-pagination, что бы он работал

339
Ошибка ajax скрипта в Firefox, который работает в Google Chrome

Ошибка ajax скрипта в Firefox, который работает в Google Chrome

Друзья, портирую расширение из Chrome на FirefoxУ FF много своих особенностей с которыми нужно как то найти общий язык

370