Table of Contents

How to Add Documenting (XML) Comments to Code

The first thing you need to do if you've not done this already is to fork this GitHub repo. All the changes you make will be made on your local fork. To incorporate them simply use a Pull Request (PR) from your fork to the main branch of this repo. That said, adding documenting comments is a simple process that goes pretty quickly once you get the hang of it.

  1. Locate the .cs file in the src_stripped folder containing the code to which you'd like to add or modify documentation generating comments. Documentation-generating comments are those that begin with a triple slash (///), and they inform the generation of the XML file, so they include XML tags that enable them to be parsed to generate the XML file.
  2. Open that file in the editor of your choice. Note that editing in Visual Studio or other similarly capable coding-oriented editors may make the following steps easier and automate the generation of some basic comments and structure.
  3. Navigate to the start of the method or the definition line for the object you would like to document.
  4. Insert a new blank line directly above and start a triple slash (///) comment. If your editor is a sufficiently smart coding-aware editor it may detect that you've started a triple-slash comment and start you out with some comments, but it may also start you out with some misinformation based on the stripped nature of the cs file. The bare minimum for documentation-generating comments is a summary block like this. All you need to do is to populate the /// comment line(s) between the <summary></summary> tags with information that summarizes what this object is used for or what this method does.
    /// <summary>
    /// Your helpful comments documenting what this is used for or what this does go here!
    /// You can have as many lines as you like. Each line defines one paragraph of documentation.
    /// </summary>
  1. If the code you're adding documentation generating comments to is a method that takes arguments you can document them like this example for a method that takes two input arguments: newPosition and newVelocity.
    /// <param name="newPosition"></param>
    /// <param name="newVelocity"></param>
  1. If the code you're adding documentation generating comments to is a method or function that returns a result there is generally no need to add that to the <return></return> block as the method has to declare its return type so this will already be apparent in the autogenerated documentation. if you really need to reiterate what it is, the technically correct way would be like the example shown below. Typically in C# documentation comments you rarely ever have to specify the type because that's always known.
    /// <returns><see cref="List{ManeuverNodeData}"/></returns>
  1. NOTE: All methods in the src_stripped folder have been stripped to only throw null; consequently if you're using a code-aware editor it may automatically add a line like this, which you should delete as the real code doesn't do this, so it would be incorrect to document it as doing so. DocFx will ignore these lines, but it will also report warnings for them, so please remove them as this aids in making sure the DocFX results are correct.
    /// <exception cref="NullReferenceException"></exception>

Rinse and repeat for as many objects and methods as you would like to add documenting comments to, then create a PR to get your updates into the main branch of this repo.

Edit this page