Document generation in C#

Document generation in C#

Why document?
One of the most famous nightmares among the developers is generating the detailed documentation of the code they have already done. But this notion should be changed as one should always detail each and every aspect of the code they have produced. Proper documentation not only helps others to understand the code but also brings down the maintenance cost of the project if properly utilized.

When to document?
I usually prefer to document things but it depends on the following factors Size of Project, Complexity of Code, Client Need etc. One should not consider the Cost of the project as a factor affecting the decision you know why?

What to document?
No matter whatever the piece of code is you can comment it and latter when needed can produce the required document for that particular section. Namespace, Class, Structure, Interface, Enum, Property, Method, Event and all other stuff can be documented. Always follow the practice of commenting your code as and when you finalize with that particular section.

 Solution

C# has an inbuilt feature than one can take the advantage to generate the document automatically. You just need to be aware of the attributes used for placing and formatting the comments. Some of them are mentioned below

[sourcecode language="csharp"]
<c> Use to depict a code into a single line.
E.g.: <c> int i = 0 ; </c>

<code> Use to depict a code snippet into a multiple lines
E.g.: <code>
for (int i = 0; i < 10; i++)
{
//Code
}
</code>
<example>
Use to depict a code example of how to utilize particular type or member.
<example> This sample shows how to call the GetEmployee method.
<code>
class Employee
{
public static int Main()
{
return GetEmployee();
}
}
</code>
</example>

<list>
Use to depict a bulleted, numbered, tabled list.

<param>
Use to depict the parameters of the method, events etc
E.g.: <param name='name'>description</param>

<paramref>
Use to depict the name of the parameter.
E.g.: <paramref name=’name’/>

<remarks>
Use to depict additional information about the type or member.
E.g: <remarks>Additional information goes here</remarks>

<returns>
Use to depict the return value of a method.
E.g: <returns>Returns List<Employee></returns>

<see>
Use to depict links to similar topics from within the text or highlights the text in the page.
E.g: <see href="www.google.com">Google</see>
<see langword="true | false"/>

<seealso>
Use to depict links to similar topics at the very end of the documented page similar to 'See also' section of the MSDN help.
E.g: <seealso href=" www.google.com">Google</seealso>

<summary>
Use to depict a small description of the type or the member.
E.g: <summary>description</summary>

<value>
Use to describe the value of the property.
E.g: <value> description</value>
[/sourcecode]

Taking into consideration that you have beautifully commented each and every piece of your code you can generate the document with just few clicks.

Practice Lesson

Step 1) Create a class library project named Document
Step 2) Add a class named Employee to the project.
Step 3) Copy past the code below

[sourcecode language="csharp"]

using System;
using System.Collections.Generic;
using System.Web;

namespace Document
{

/// <summary>
/// Summary description for Employee
/// </summary>
public class Employee
{
/// <summary>
/// Employee Class default constructor
/// </summary>
public Employee()
{

}

/// <summary>
/// Employee Class constructor
/// <c>Employee objEmployee = new Employee('dhaval',25)</c>
/// </summary>
/// <param name="name">Name of the employee</param>
/// <param name="age">Age of the employee</param>
public Employee(string name, int age)
{

}

}

}

[/sourcecode]

Step 4) Go to project properties >> build section and check XML Document file section under output group as shown below
Step 5) Build the project and go to bin\debug folder. Document.Xml file would have been generated containing all the details required to generate the document
Step 6) Open NDOC and click on add button
Step 7) Provide path of Document.dll in the assembly file name and Document.XML path in XML Doc Filename and click Ok
Step 8 Finally click Build from the ndoc toolbar or select build from documentation menu

To view the output document click View icon from ndoc toolbar or select view from documentation menu.

That’s It. You’re done

Note: Above are the very few sample tags related to the visual aspect of the document generation there are number of tags that can handle various other aspect of the document generation like permission, threading, include, exclude etc.

As the internal architecture of the NDOC is based on XML and XSLT one can also generate the Custom Tags of their own.

To play around more you can take the reference of the below official site of NDOC

http://ndoc.sourceforge.net/usersguide.html