Author : HASSAN MD TAREQ | 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>
/// <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>