c# - 将常量呈现到 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).

我的问题是：有没有办法将我的 const 呈现到我的 XML 文档中？

---

我想出的替代方案是：

1. 只需在文档中写 24 和 29 （缺乏对实际值的依赖）
2. 公开 consts 并添加<see cref="MinAge">and <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

我认为没有任何方法可以在文档_minAge和_maxAge文档中编写常量的实际值，但是您可以使用以下标记来引用它们<see>：

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

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

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; 
    }

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

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