Могу ли я использовать <inheritdoc cref> для ссылки на сводку XML другой переменной?

Question

Когда я пишу функции для своего проекта, а точнее, их комментарии к XML-документации, я часто повторяю комментарии для определенного параметра. Иногда это приводит к вводящей в заблуждение документации (как это обычно бывает при копировании...).

Это простой пример, о котором я подумал, который представляет настоящую проблему.

/// <summary>
/// The number that should be doubled
/// </summary>
private static float myNumber = 10f;

/// <summary>
/// Multiplies a number by 2
/// </summary>
/// <param name="number"><inheritdoc cref="myNumber"/></param>
/// <returns>The number multiplied by 2</returns>
private static float MultiplyByTwo(float number)
{
    return number * 2f;
}

В этой строке /// <param name="number"><inheritdoc cref="myNumber"/></param>, Я бы хотел, чтобы текст "Число, которое следует удвоить", но он не отображается. Возможно, я не совсем понимаю использование inheritdoc.

Под появлением я имею в виду следующее. Visual Studio должна показать документациюnumber в этой коробке:

Вот как это должно выглядеть (без копирования и вставки текста):

Итак, есть ли способ ссылаться на другую переменную в комментариях к документации XML?

Answer 1

В Visual Studio 16.8.4 я могу использовать для этого атрибут .

      /// <summary>
/// The number that should be doubled
/// </summary>
private static float myNumber = 10f;
        
/// <summary>
/// Multiplies a number by 2
/// </summary>
/// <param name="number"><inheritdoc cref="myNumber" path="/summary"/></param>
/// <returns></returns>
private static float MultiplyByTwo(float number)
{
    return number * 2f;
}

В атрибуте выбирает «корневой» узел, а затем summaryэто узел, который нужно выбрать в этом узле.

Результат:

Атрибут использует синтаксис XPath, о котором вы можете узнать подробнее здесь .

Вы можете использовать его, чтобы делать отличные вещи, если будете осторожны; Я регулярно использую его при реализации Try[...]шаблон.

Например:

      /// <summary>
/// This throws!
/// </summary>
/// <param name="param1">This is a parameter.</param>
/// <param name="param2">This is another parameter!</param>
/// <exception cref="InvalidOperationException"/>
public string ExampleThatCanThrow(int param1, float param2)
{
    throw new InvalidOperationException();
}

/// <summary>
/// This never throws!
/// </summary>
/// <inheritdoc cref="ExampleThatCanThrow(int, float)" path="/*[not(self::exception)]"/>
public bool TryExample(int param1, float param2, out string? result)
{
    result = "No throwing here!";
    return true;
}

Обычно при использовании <inheritdoc>для TryExampleметод таким образом, он показал бы, что он может бросить InvalidOperationException. С использованием pathатрибут, я отфильтровал его, поэтому будут унаследованы только узлы, которые не соответствуют имени.

/: соответствует корневому узлу.

*: соответствует любому дочернему узлу.

[а также ]: соответствует любому узлу, соответствующему условиям содержащегося предиката.

not(): Соответствует любому узлу, который не соответствует условиям выражения в круглых скобках.

self::exception: Соответствует текущему узлу, если он имеет имя exception.

Это приводит к следующему: