Рендеринг констант в документацию XML?

Question

У меня есть 2 частных контеста и публичный метод:

private const byte _minAge = 24;
private const byte _maxAge = 29;

public bool IsInAgeRange() { ... }

Я добавляю документацию в формате XML и хотел бы, чтобы пользователи моего кода могли прочитать это в IntelliSense: Checks whether the age is within the allowed range (between 24 and 29).

У меня вопрос: есть ли способ сделать мои констант в моей документации XML?

---

Альтернативы, которые я придумал:

1. Просто напишите 24 и 29 в документации (отсутствует зависимость от реальных значений)
2. Сделайте общедоступными и добавьте их <see cref="MinAge"> а также <see cref="MaxAge"> (уменьшает инкапсуляцию и делает документацию менее информативной)

Answer 1

Добавьте сводку к каждой константе, содержащей значение, а затем обратитесь к этим комментариям:

/// <summary>24</summary>
private const byte _minAge = 24;
/// <summary>29</summary>
private const byte _maxAge = 29;

/// <summary>Checks whether the age is within the allowed range (between <inheritdoc cref="_minAge"/> and <inheritdoc cref="_maxAge"/>).</summary>
public bool IsInAgeRange() { ... }

Я знаю, что это все еще дублирование, но таким образом вы можете хранить свои постоянные комментарии рядом с вашими константами, даже если константы полностью определены в другом файле.

Answer 2

Это объединяет ответ от @kalu93 и комментарий от @DhyMik, чтобы показать, как вы можете использовать <inheritdoc/> в обоих <summary> тег и <param> тег:

          /// <summary>24</summary>
    private const byte _minAge = 24;
    /// <summary>29</summary>
    private const byte _maxAge = 29;

    /// <summary>
    /// Checks whether the age is within the allowed range 
    /// (between <inheritdoc cref="_minAge"/> and <inheritdoc cref="_maxAge"/>).
    /// </summary>
    /// <param name="TheAge">
    /// Age (must be between <inheritdoc cref="_minAge" path="//summary"/> and 
    /// <inheritdoc cref="_maxAge" path="//summary"/>).
    /// </param>
    public bool IsInAgeRange(int TheAge) { 
      return _minAge <= TheAge && TheAge <= _maxAge; 
    }

Visual Studio теперь правильно показывает ограничения при наведении курсора на функцию. IsInAgeRange:

... а также при наведении курсора на параметр TheAge:

Answer 3

Я не думаю, что есть какой-либо способ записать фактическое значение констант _minAge а также _maxAge в документации, но вы можете обратиться к ним с помощью <see> пометьте следующим образом:

/// <summary>
/// Checks whether the age is within the allowed range (between <see cref="_minAge" /> and <see cref="_maxAge" />).
/// </summary>

Теперь это создаст ссылку на эти константы в вашей документации, так что когда вы создадите свои документы и отредактируете их позже, пользователь сможет кликать по этим ссылкам и ссылаться на соответствующие константы.