(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:
/// Our logger….
public class Logger
/// Log the given message…
/// <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).
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?