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>
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>