XML comments

Note that previously we did not use a Tooltip attribute on the private rb variable. Since it's not being displayed in the editor, it's not really needed. However, there is a way that we can enhance that as well, making use of XML comments. XML comments have a couple of nice things that we get when using them instead of traditional comments, which we were using previously. When using the variables/functions instead of code in Visual Studio, we will now see a comment about it. This will help other coders on your team have additional information and details to ensure that they are using your code correctly.

XML comments look something like this:

/// <summary> 
/// A reference to the Rigidbody component 
/// </summary> 
private Rigidbody rb;

It may appear to be a lot more writing is needed to use this format, but I did not actually type the entire thing out. XML comments are a fairly standard C# feature, so if you are using MonoDevelop or Visual Studio and type ///, it will automatically generate the summary blocks for you (and the param tags needed, if there are parameters needed for something like a function).

Now, why would we want to do this? Well, now, if you select the variable in Intellisense, it will display the following information to us:

This is a great help for when other people are trying to use your code and it is how Unity's staff write their code. We can also extend this to functions and classes to ensure that our code is more self-documented.

Unfortunately, XML comments do not show up in the Inspector, and the Tooltip attribute doesn't show info in the editor. With that in mind, I used Tooltips for public instructions and/or things that will show up in the Inspector window, and XML comments for everything else.

If you're interested in looking into XML comments more, feel free to check out: https://msdn.microsoft.com/en-us/library/b2s063f7.aspx.