XML comments & Doxygen generation

Make your comments show up in your IDE’s tooltips and clarify the design intent behind every entity in your code with automatically generated interactive documentation.

XML Comments

All you need to do to start using XML comments is to type /// in the line above an entity declaration such as a namespace, class, variable or function like this:

///
void FunctionName ()
{

}

It will instantly produce a template for you to fill out like this:

 ///<summary>;
 ///
 ///</summary>;
 void FunctionName ()
 {

}

You enter a one-line description of what the entity does a short reminder of how to use it.

If you want to clarify in more detail the design intent of the entity, you can add another few lines with <remarks></remarks> like this:

///<summary>;
/// FunctionName does what its name would suggest 
/// <summary>;
/// <remarks>;
/// More in-depth description of what the entity is for, 
/// the way in which it should be used, etc.
///
/// ## Markdown headers and other tags work too
/// You can use lots of markdown to make your remarks show up nice
/// when you generate Doxygen documentation (more on that below)
///</remarks>;
void FunctionName ()
{

}

If you have arguments and return values before you first make the XML comment with \\\, it will make you param and return tags like this to fill out:

///<summary>;
/// Converts int to string
///</summary>;
/// <param name="intToConvert">The int to be converted</param>;
/// <return>Returns the int converted into a string</return>;
public int IntToString(int intToConvert)
{
    return int + "";
}

These comments will show up in tooltips when you mouse over references to the entity elsewhere in your code and in autocomplete boxes.

Using Resharper to reformat XML comments

Visual Studio and other C# editors create summary tags that take 3 lines rather than inlining the whole tag on one line like this:

/// <summary>;
/// your description
/// </summary>
Entity

For large numbers of entities commented in a row, this can eat up the screen space and make it hard to see much code at once.

Fortunately, you can use Resharper to set rules for reformatting your XML comments onto single lines and then use Resharper’s context menu to trigger Clean Up and use a custom clean up profile that just reformats XML comments the way you want them. This will change all your code to use shorter 1-line comments like this:

/// <summary> description of the entitty </summary>;
Entity

Doxygen Generation

Have you ever wondered how SDK developers like Apple and Unity make nice interactive API docs? They make it with automated tools based on comments in the code itself.

Once your code contains XML comments, you can use a free tool called Doxygen to automatically create interactive HTML docs.

You can download Doxygen here:

http://www.stack.nl/~dimitri/doxygen/download.html

You’ll need to configure it to point it at the Unity Assets folder.

You’ll probably want to narrow its focus down to only the scripts in your own game, otherwise you’ll see documentation generated for all the asset store plugins you use.

Doxygen Generation

Once your code contains XML comments, you can use a free tool called Doxygen to automatically parse your code and create interactive HTML documentation.

You can download Doxygen here:

http://www.stack.nl/~dimitri/doxygen/download.html

Start with Unity Plugins

The quickest way to get it to work is with a Unity plugin that configures it for you. There’s two Unity plugins, DoxyTool  and DoxygenForUnity, that will help you generate Doxygen from within a Unity project.

Customize Doxygen

To manually customize Doxygen for the best results, there are lots of options.

You’ll need to configure it to point it at the Unity Assets folder.

We’ll add to this list of favorite Doxygen config tweaks here as we remember them and receive suggestions in comments:

• Narrow the path down to only the scripts in your own game, not asset packs
• Put the detailed remarks description at the top right below the summary
• Customize the CSS colors and fonts

Do you have favorite commenting and Doxygen tricks you would like to share? Post them in the comments.

Learn more about XML comments

There are lots more cool tricks you can use and a summary of all the XML comment tags that are supported by Doxygen is available here:

http://www.stack.nl/~dimitri/doxygen/manual/xmlcmds.html