将常量渲染到XML文档中？

Question

我有2个私有consts和一个公共方法:

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. 使consts公开并添加<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

我认为没有任何方法可以在文档中写入常量的实际值_minAge，_maxAge但您可以使用标签引用它们，<see>如下所示：

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

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

Answer 3

<inheritdoc/>这结合了 @kalu93 的答案和 @DhyMik 的评论，以展示如何在<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：