Rendering constants into XML documentation?

Question

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:

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

I wanted to know the same since it is possible in JavaDoc. But seems it isn't possible with .net's documentation? :( — AnorZaken, Mar 11 '15 at 18:39
Have you (or anybody else) created a feature request for C#? If yes, please add the link here. If not, I suggest you create one. — Tobias Knauss, Jan 21 '21 at 07:01

score 16 · Accepted Answer · answered Aug 31 '20 at 12:18

16

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.

answered Aug 31 '20 at 12:18

kalu93

226
2
4

1

Accepted as "best workaround so far" :) Thanks! Dear reader, if it ever becomes natively supported please do post a new answer and I will re-evaluate. – tsemer Sep 28 '20 at 10:48
3

For others trying this, note that it only works inside the `
` tag. I tried it inside the text of a `` tag and it didn't work. Furthermore, if you are using Swagger to document ASP.NET Web APIs, using the `` tag doesn't work correctly (the XML is rendered verbatim instead of rendering the actual inherited docs - see this [issue](https://github.com/domaindrivendev/Swashbuckle.WebApi/issues/1000)).
– Eric Mutta Apr 16 '21 at 11:56
4

@EricMutta When `` is used inside of a tag and only cref but no path value is specified, then by default `` will reference only the same tag in the ref target. So if you use `` inside of a `` tag, only the content of the same `` tag of the ref target will be used. If you want to reference the content of the summary tag of the ref target like above in @kalu93's answer from inside a `` tag, use ``. The path option uses XPath notation to select the referenced target. – DhyMik Jun 11 '21 at 11:29
8

I would suggest using the `` tag for this rather than putting the number inside of the `
` tag. It's more semantic and leaves the `
` tag for more relevant content. The value can then be referenced with ``
– DhyMik Jun 11 '21 at 11:32
@DhyMik thanks for the tip! I have added an answer that combines your tip with @kalu93's answer. For anyone else who may have missed the `path` attribute of `` it's actually documented in the [official docs](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/inheritdoc#path) (complete with an example, scroll down to the `InheritOnlyReturns` class in that link). – Eric Mutta Jun 11 '21 at 12:26

score 4 · Answer 2 · answered Oct 17 '12 at 10:45

4

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.

answered Oct 17 '12 at 10:45

nickolayratchev

1,136
1
6
15

5

You seem to be repeating what I mentioned in my alternative #2; see drawbacks there – tsemer Oct 17 '12 at 14:21
Ha, well, since I answered before you edited your question, I can argue that *you* repeated what I wrote in my answer :P – nickolayratchev Oct 17 '12 at 18:10
1

The bottom part was always there, the edit was just a spelling mistake – tsemer Oct 18 '12 at 07:19
strange ... must not have noticed it sorry. In any case, that is the only solution I know. I think if you have the comment in the same class as your private `consts`, it should work without having to make them public? – nickolayratchev Oct 19 '12 at 03:37
No worries thanks for your time anyway :) Private does compile, only it shows to the intellisense user `...between _minAge and _maxAge`, and the user can never know what those values really are since he has no access to those consts. – tsemer Oct 19 '12 at 07:31
3

Yes, I guess that doesn't work. But then you can ask yourself, why are the constants private when the `IsInAgeRange()` is public? How come the user can validate the object's age but does not know the conditions under which it is considered valid? – nickolayratchev Oct 19 '12 at 07:42

score 2 · Answer 3 · answered Jun 11 '21 at 12:21

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:

Rendering constants into XML documentation?

3 Answers3

Linked