Documentation comments

The past few days I've been working through some of my engine and game code replacing my usual comments with documentation comments and I thought I'd make a quick post about it since it seems to be something very few people do.

To get started, simply find one of your own functions and type three slashes on the line above it. As if by magic, Visual Studio will add in an XML comment block where you can enter a description of the function's purpose and it's parameters. The snippet on the left shows an example of this, simply from pressing ///.

Simply then fill in all of your details into the auto generated XML to enable the Visual Studio interface to show helpful hints while you're writing your code. Be sure to be nice and descriptive as this will come in handy in the future. In the shot to the left I've filled in the details for the function which is from a tower defense game I'm making.



The two little snippets above show the hints Visual Studio will generate from your API comments. The first is a handy line of text telling you what the function does in the auto-complete box. The second describes what each parameter is for when you're calling the function.

If you found this post helpful please leave a comment below: