How to activate xml documentation in Visual Studio .Net 2005

(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”:


NoCommentOnLogger.gif


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:


NoCommentOnLogMethod.gif


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).


CommentOnLogger.gif     


CommentOnLogMethod.gif


 


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?

 

Oren Ellenbogen

 

2 thoughts on “How to activate xml documentation in Visual Studio .Net 2005

  1. One has to wonder why not simply refactor the class name to OurLogger and why must we repeat the command in the name of the parameter and a comment.

    This is a good example on how to Activate XML Commenting but not why should we use it.

Comments are closed.