C# Documentation comment

Author : MD TAREQ HASSAN | Updated : 2020/08/01

Doc comment structure

html tags are allowed in doc comment
use <![CDATA[ ... ]]> when embedding code sample in doc comment

summery should end with a period (as like first line of java doc comment)

/// <summary>
/// Summary tags should only contain the most important information. For details use an additional remarks tag.
/// </summary>
/// <remarks>
/// <para>Here goes long description.</para>
/// <para>Here goes long description.</para>
/// </remarks>

Class

/// <summary>
/// Each class should have a summary tag describing its responsibility. 
/// The summary often starts with “Represents …“ or “Provides …“ but other forms also exist
/// </summary>

Contructor

/// <summary>
/// Initializes a new instance of the <see cref="MyClass">MyClass</see> class.
/// </summary>

Methods

/// <summary>
/// Like the method name itself, the text in the summary tag should start with a verb.
/// </summary>
/// <param name="fooId">The Foo ID.</param>
/// <returns>Foo for the given ID.</returns>
public Foo FindFoo(int fooId)
{
  // ... ... ...
}

When retur type is bool

/// <returns><c>true</c> if the person could be found; otherwise, <c>false</c>.</returns>

Embedding links to other classes, properties, methods

/// <summary>
/// Go on, have a look at <see cref="MyClass"/>
/// Go on, have a look at <see cref="MyClass.MyMethod"/>
/// Go on, have a look at <see cref="MyClass.MyProperty">Custom text</see>
/// </summary>

Embedding code example

/// <example>
/// Below is an example of using MyMethod to do something.
/// <code>
/// <![CDATA[
/// MyClass a = new MyClass();
/// string result = a.MyMethod();
/// ]]>
/// </code>
/// </example>

Exception

/// <exception cref="InvalidOperationException">
/// Here you describe why the exception will be thrown.
/// </exception>

Generate html

Install docfx:

choco install docfx -y

Initialize docfx:

Visual Studio > View > terminal (Developer PowerShell will open)
By default location will be the solution folder: docfx init -q

Generate html for a project located in a different folder: https://stackoverflow.com/a/65608712/4802664 docfx.json

      "src": [
        {
          "files": [
            "**.csproj"
          ],
          "src": "../ProjectA"
        }
      ],

Add doc comment, make sure that classes, methods are publc (by dafult, for private and internal access modifier, documentation will not be generated).

docfx docfx_project/docfx.json

# when we run the command from docfx_project folder (cd docfx_project)
# just docfx is enough

docfx serve docfx_project/_site