Search code examples
c#visual-studioxml-documentation

Rendering constants into XML documentation?


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:

  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)

Solution

  • 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.