Today I had reason to do something I haven’t had to do in a really long time: add IntelliSense hints to a library we supply. Because it’s been so long since I last did this, I had to look up one or two details, so I thought I’d share a quick summary.
There are two parts of this: adding XML comments to your code, and ensuring that this XML is made available to consumers of your code.
Adding XML comments
To add some XML comments to your code in Visual Studio, simply type three slashes ( \\\) on a line immediately above the declaration of a namespace, class, method, property, or field. Visual Studio will automatically expand this to at least an XML summary:
|
1 2 3 |
/// <summary> /// Put your summary here /// </summary> |
But Visual Studio really shines when we type our slashes above more interesting signatures. Visual Studio will detect parameters and return values and will automatically provide the elements for these in your XML comments:
|
1 2 3 4 5 6 7 8 9 |
/// <summary> /// Multiplies the MagicNumber by another /// </summary> /// <param name="Multiplier">The number to mutiply the MagicNumber by</param> /// <returns>MagicNumber multiplied by Multiplier</returns> public int MultiplyMagicNumber(int Multiplier) { return MagicNumber * Multiplier; } |
This XML comments will lead to the following IntelliSense:
Intellisense in action
In addition to the “summary”, “param” and “returns” elements I’ve used above, there are lots of additional tags you can use in XML comments. You can even create your own.
If like me, your main motivation is to provide info to consumers of your code using IntelliSense however, these three (plus “typeparam”) should be all you’ll need.
Ensuring your documentation is available
Now that you’ve gone to the effort of documenting using XML comments, how can we make sure this documentation is available to consumers of your code? As you might suspect, this depends somewhat on your mode of distribution.
If you’re simply adding one project as a reference to another within the same solution, good news: you don’t need to do anything!
If you’re supplying your code as a binary, things get a little (not a lot) more complicated. The first thing to do is to tell Visual Studio to collate your XML comments into a single XML file during the build process. (This is the bit I’d forgotten how to do!) Luckily it’s as simple as a single checkbox on the Build tab of the project properties:
The build tab of project properties
Or, if you’re building from the command line, just add the /doc parameter:
|
1 |
csc SharedClass.cs /doc:SharedClass.xml |
However you generate the XML, you just need to ship the resulting XML file alongside your binary artefacts.
If you’re using NuGet (or similar), you can include your XML documentation file in your package with a simple addition to the NuSpec:
|
1 2 3 4 |
<files> <file src="bin\SharedLibrary.dll" target="lib\Net40" /> <file src="bin\SharedLibrary.xml" target="lib\Net40" /> </files> |
If you’d like to see this in action, I’ve put a demo up on GitHub. It has both a project reference and a binary reference.
Summary
So there we go. Told you it was simple! All we’ve done is add some XML documentation in some specially crafted (triple slash) comments and then ticked a box in the project properties.
As if by magic, the consumers of your code libraries can benefit from your guidance right inside Visual Studio.If you write code that’s used by others (especially outside of your organisation) consider taking an hour or so to
If you write code that’s used by others (especially outside of your organisation) consider taking an hour or so to add XML comments. I’m sure your colleagues / collaborators / clients will thank you for it!