(Before you start - give a look at C# and XML Source Code Documentation)
So you build up a nice API that everyone can use but you want to provide nice, IntelliSense-enabled comments along with your magical code right?Let's say I have the class Logger in my "Infrastructure" dll:
/// <summary>/// Our logger..../// </summary>public class Logger{ /// <summary> /// Log the given message... /// </summary> /// <param name="messageToLog">The message to log.</param> public void Log(string messageToLog) { }}
Now, my clients(e.g other teammates) want to use this logger. Adding a quick "File Reference" to the dll and they are good to go. This is great _but_ they also want to see the comments I provided as they type (IntelliSense in action baby). Surprisingly enough, they will _not_ see it "by default":
As you can see (well, not see, but that's my case) - we don't see the class comment "Our logger...". The same goes for our Log method:
Where are my comments ?!!?
Well, it turns out that you should make a small change to make it alright. Say hello to "XML Documentation file". Open the Project Properties, under the "Build" tab there is a little checkbox named "XML Documentation file" - make sure it's checked and you're done!All you have to do is to recompile the dll and add the reference again (e.g remove & add, Dumb, but works) or manually copy the generated xml file to your bin directory (if CopyLocal = true).
Conclusions:
You should always make sure that "XML Documentation file" is checked! Why providing comments if no one can see them (unless you have access to the code and you make a "Project Reference").
I'm not sure why Microsoft made this checkbox unchecked as default. Am I missing something here?
Remember Me
Disclaimer The opinions expressed herein are my own personal opinions and do not represent my employer's view in anyway.
© Copyright 2008, Oren Ellenbogen
<= Contact me via E-mail
newtelligence dasBlog 1.9.6264.0