I have 2 private consts and a public method:
private const byte _minAge = 24; private const byte _maxAge = 29; public bool IsInAgeRange() { ... }
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).
My question is: Is there a way to render my consts into my XML documentation?
The alternatives I've come up with are:
<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.
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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With