1

Is there a proper way of describing a Dictionary type variable or a KeyValuePair with documentation comments in C#.

Something like this,

/// <summary>
/// User credentials
/// </summary>
/// <key>username</key>
/// <value>password</value>
private static Dictionary<string, string> credentials;
NeWi-SL
  • 127
  • 1
  • 6
  • 3
    There's no specific tag listed in [the Microsoft docs](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) or [the Sandcastle help](https://ewsoftware.github.io/XMLCommentsGuide/html/4268757F-CE8D-4E6D-8502-4F7F2E22DDA3.htm). – Richard Deeming Dec 10 '21 at 14:58
  • Oh! That's a shame. Can't we even put something like `` ? @Richard Deeming – NeWi-SL Dec 10 '21 at 15:07
  • `` applies to a method or indexer parameter. `` applies to a generic type parameter, but only on the open generic type / method. There's no standard tag to document the type parameters of a closed generic type. – Richard Deeming Dec 10 '21 at 15:20

2 Answers2

2

Not sure what you really need here, but maybe like this?

/// <summary>
/// Dictionary of passwords by username
/// </summary>
Dictionary<string,string> Passwords

Good names are really your best doc, which you can supplement with the summary tags (or others as well).

Alternatively, you could make a custom class that inherits Dictionary and then provide a custom .Add(username,password) method and add comment tags to that. Or same thing, but Extend Dictionary instead.

RBarryYoung
  • 55,398
  • 14
  • 96
  • 137
  • 1
    @NeWi-SL: if you have the urge to inherit from `Dictionary`, you may want to go through this: https://stackoverflow.com/questions/21692193/why-not-inherit-from-listt. Similar reasoning holds here. I wrap dictionaries all the time (and, remember, with the _Collection Initialization Pattern_ you can make your class's construction/initialization look like a Dictionary's). I can't think of a good reason to extend one – Flydog57 Dec 10 '21 at 15:07
  • Thanks a lot you both @Flydog57 I have updated the question little bit. Hope it might help you to get an idea of what I am trying to say. – NeWi-SL Dec 10 '21 at 15:11
2

As already mentioned, there is no way to document such types in a structured way. I do this with a free text inside a <value> tag. This tag is primarily designed for properties but it's displayed in Intellisense also for fields.

My comment would look as follows:

/// <summary>
/// User credentials.
/// </summary>
/// <value>The collection of credentials where the key is a username and the value is a password.</value>
public static Dictionary<string, string> credentials;
Peter Macej
  • 4,831
  • 22
  • 49