将常量渲染到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).

我的问题是： 有没有办法将我的consts渲染到我的XML文档中？

---

我提出的替代方案是：

1. 只需在文档中写入24和29（缺乏对实际值的依赖）
2. 将公告公开并添加<see cref="MinAge">和<see cref="MaxAge">（减少封装并减少文档信息量）

Answer 1

我认为没有办法在文档中写出常量_minAge和_maxAge的实际值，但您可以使用<see>标记来引用它们，如下所示：

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

现在，这将创建一个指向文档中这些常量的链接，这样当您生成文档并在以后呈现它们时，用户将能够单击这些链接并引用相应的常量。

Answer 2

向包含该值的每个常量添加摘要，然后参考这些注释：

/// <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 3

这结合了@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; 
    }

现在，当您将鼠标悬停在函数 IsInAgeRange 上时，Visual Studio 会正确显示限制：

...以及当您将鼠标悬停在参数 TheAge 上时：