Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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)
like image 479
tsemer Avatar asked Oct 17 '12 10:10

tsemer


2 Answers

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.

like image 85
kalu93 Avatar answered Oct 11 '22 05:10

kalu93


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.

like image 33
nickolayratchev Avatar answered Oct 11 '22 07:10

nickolayratchev