将常量渲染到 XML 文档中? [英] Rendering constants into XML documentation?

问题描述

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

I have 2 private consts and a public method:

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

public bool IsInAgeRange() { ... }

我正在添加 XML 文档，并且希望我的代码用户可以在 IntelliSense 中阅读此内容:检查年龄是否在允许的范围内(介于 24 和 29 之间).

I am adding XML documentation, and would like it best if the users of my code could read this in IntelliSense: Checks whether the age is within the allowed range (between 24 and 29).

我的问题是:有没有办法将我的常量渲染到我的 XML 文档中?

My question is: Is there a way to render my consts into my XML documentation?

我提出的替代方案是:

1. 在文档中简单地写下 24 和 29(缺乏对真实值的依赖)
2. 公开常量并添加 和 (减少封装并制作文档信息量较少)

1. Simply write 24 and 29 in the documentation (lacks the dependency to the real values)
2. Make the consts public and add <see cref="MinAge"> and <see cref="MaxAge"> (reduces encapsulation and makes documentation less informative)

推荐答案

为每个包含值的常量添加摘要，然后参考那些评论:

Add a summary to each constant containing the value, then refer to those comments:

/// <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() { ... }

我知道这仍然是重复的，但是这样您可以将常量注释保持在常量附近，即使常量完全在另一个文件中定义也是如此.

I know it's still duplication, but this way you can keep your constant comments near your constants, also if the constants are defined in another file entirely.

这篇关于将常量渲染到 XML 文档中?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！