Csharp xml docs

Documentation

official docs	https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/
xml tags	https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

Usage

Commandline

APIdoc generation is created in two steps.

1. C# produces an XML file
2. that XML file is used to generate docs

Official recommendations:

• https://dotnet.github.io/docfx/

Syntax

Components

Doc Domments

Doc comments are indicated by triple-slashes above the function.

/// <summary>
///
/// </summary>
public class MyClass
{
    //
}

C# also supports javadoc style comments

/** <summary>blah</summary>
 */

Tags

You use XML tags in your class.

/// <summary> Description of blah <c>inline-code</c> and blah
/// </summary>
///
/// <param name="message">message to print</param>
/// <param name="age">age of receiver of message</param>
///
/// <example>
///   <code>
///     void print_msg(message, age) {...}
///         // multiline code
///   </code>
/// </example>
///
/// <returns>1 if fails, 0 if succeeds</returns>
/// <seealso cref="MyClass.Print"/>

public class MyClass
{
    int Print(message)
    {
        // ...
    }
}

You can also source documentation from an external file (using a relative path from the current sourcefile).

/// <include file='filename.doc' path='tag/path[@name="Print"]'/>  
public class MyClass
{
    int Print(message)
    {
        // ...
    }
}

<?xml version="1.0"?> 
<!-- filename.doc -->
<tag>
  <path name="Print">Print method documentation</path>
  <path name="Main">Main method documentation</path>
</tag>

https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments