Rendering constants into XML documentation?
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.
This combines the answer from @kalu93 and the comment from @DhyMik to show how you can use <inheritdoc/>
in both the <summary>
tag and <param>
tag:
/// <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 now shows the limits properly when you hover over the function IsInAgeRange
:
...as well as when you hover over the parameter TheAge
:
I do not think there is any way to write the actual value of the constants _minAge
and _maxAge
in the documentation, but you can refer to them using the <see>
tag as follows:
/// <summary>
/// Checks whether the age is within the allowed range (between <see cref="_minAge" /> and <see cref="_maxAge" />).
/// </summary>
Now, this will create a link to those constants in your documentation, so that when you generate your docs and render them later on, the user will be able to click on those links and be refered to the appropriate constants.