Dictionary - Add comments to drive intellisense

Question

Is there a way to add comments to document a Dictionary or ConcurrentDictionary to know what the key / values mean?

For example:

Dictionary<guid, string> _users;

This example has a dictionary of users. The guid is the UserId and the string is the username, but it's hard to tell other than just "knowing".

Is there a way to add docs so that when you add items, intellisense tells the developer a note about the key & value?

I know I can add a <summary> comment above it and it puts that note in the object itself, but was looking for when adding, removing, etc.

Answer 1

Recently in GOOS book I found interesting idea of packaging common types (such as collections) in own classes:

Try to use the language of the problem you are working on, rather than the language of .Net constructs. It reduces conceptual gap between domain and code. Also try to limit passing around types with generics. This is a form of duplication. It's a hint that there is domain concept that should be extracted to type.

Frankly speaking I'm not so extremal in packaging common generic collections, but even giving a type own name makes it match easier to read and understand:

public class UserNameDictionary : Dictionary<int, string>
{
}

Very simple. And now what is better to read:

Dictionary<int, string> users = new Dictionary<int, string>();
UserNameDictionary users = new UserNameDictionary();

Also you can quickly add comment to your class:

/// <summary>
/// Represents a dictionary of user names accessed by ids.
/// </summary>

This will not add comments to methods like Add(int, string), but when other people will use this class, they will think in context of UserNameDictionary, not in abstract Dictionary<int, string> context.

If you want to make your class more handy, you can hide base class methods:

public new void Add(int userId, string userName)
{
    base.Add(userId, userName);
}

For more complex use cases I'd go with custom class which delegates work to internal dictionary.

Answer 2

For your specific case, the short answer is 'Not without a bunch of boilerplate code'.

Methods can be decorated to document what a type parameter means. The following will show what the parameters mean in Intellisense as you expect.

/// <summary>
/// Class to contain things
/// </summary>
/// <typeparam name="T">UserID</typeparam>
/// <typeparam name="TK">UserName</typeparam>
public class MyDictionary<T,TK> : Dictionary<T,TK>

You can use this to override virtual methods and document them the same. However Dictionary<,> has basically no virtuals, so you will be required to create your own calls then call 'base'. (ignoring the problematic 'new').

But then at that point, you should just go ahead with:

public class MyDictionary : Dictionary<string,string> 

and be done with it.