End of the search for a free and simple Documentation tool (Part I)

We all know the importance of documentation, but very few people really document what they are doing. So later when there is a problem we dont know what is done where. NDoc comes to our rescue. I came across this free tool by accident and found it very easy and intutive to use. We can create basic documents of our classes in a jiffy. There are also options to create professinal documentation, but with a little more effort.

In the first of this series of articles, i will create a sample C# windows application and document it. It will take around an hour from start to finish. But when we are done you can appreciate the advantage of easy documentation by adding a few comment lines as we code along.

We need NDoc to start with. Download it from here.
Then install it, make sure the check boxes for DotNet version 1.0 and 1.1 are selected during installation.

1. Create a New C# Windows Application, Name it as TestingNDoc1.
2. Rename the form name to TestForm.
3. Create a button in the Form.
4. Save the project.

The following steps have to be done for us to use NDoc sucessfully

In the main menu,

• click on Project
  
• Properties.

In the properites windows, make sure the following values are set, under

• Common Properties
• General - check if the name of the Assemble is defined
• Configuration Properties
• Build
  
• Outputs - type "NDocTestingDocument.xml" as the XMLDocument file.

This is the filename under which the class details will be stored as a xml file. This acts as input for NDoc to create our documentation.

Create a new class, name it MyClass. Then copy the following code below into it. Change the namespace accordingly as shown below

using System;

namespace MyNamespace
{
/// [summary]
/// [c]MyClass[c] created under [c]MyNamespace[/c].
/// [/summary]
public class MyClass
{
/// [summary]
/// The default [c]MyClass[c] constructor.
/// [/summary]
public MyClass()
{
aField = 0;
}

///[overloads]
///[summary]The [c]overloaded[/c] constructor for [c]MyClass[/c].[/summary]
/// [remarks]It accepts [c]one[/c] parameter[/remarks]
/// [/overloads]
/// [param name="GivenValue"]This is a [c]Integer[/c] type parameter.[/param]
/// [remarks]
/// This constructor provides the mechanism to intialize the newly created object with a default value.
/// [/remarks]
public MyClass(int GivenValue)
{
aField = GivenValue;
}

private int aField;

/// [summary]
/// [c]MyClass[/c] has this one property defined.
/// [/summary]
/// [value]The property accepts and shows the integer value in the local variable.[/value]
public int Value
{
get
{
return aField;
}
set
{
aField = value;
}
}

///[summary]
///The [c]SingleValue[/c] method assigns the given value into the local variable of [c]MyClass[/c] class.
///[/summary]
///[returns]Returns nothing.[/returns]
///[remarks]
///We can add code snippets like the below in our doumentation if required.
///[/remarks]
///[seealso href="http://ndoc.sourceforge.net/"][NDoc][/seealso]
public void SingleValue(int SomeValue)
{
aField = SomeValue;
}

}
}

Note: please replace [] with <> in the class. It has been done this way here, as the formatting is lost if given normally.

This class contains a single field, a single property and a single method. I have tried to keep as simple as possible. As u can see from the code it contains tags like [summary], [remarks] etc. These are compiled into the XML file and which make up the documentation. They are pretty much self explanatory.

Save the project.
The code should compile without any erros.
Go to the code behind of the TestForm.
Add using MyNamespace; at the top of the code behind along with the other "using members".
Double click on the button in TestForm. Then copy the following code into the button click event.

MyNamespace.MyClass aObject =new MyNamespace.MyClass(100);
MessageBox.Show(aObject.Value.ToString());

Save the project.
The code should compile without any erros.
Check NDocTestingDocument.xml has been created under the Project directory.

Run the application. When u click on the button, you should get a message box with value 100.

We are ready to document the above project.

Run NDOC, i have (DotNet1.1), so i use that version. CLick on "New from Visual Studio Solution"

Select the Solution file in the dialog box from where we have store our application. Now compile NDoc. Once its done. Click on View. You will have a ready made document in MSDN style. As u can see the drop down contains a no of options. I have used the default and common MSDN format.

Save this as a NDoc project. No need to change anything in the options given below Documentation type. We will discuss about the options in detail in the coming parts of this series.

Now Compare the code in the project with the output document. You can easily understand the code.

Go through the documentation provided with NDOC for further information.

More details for documentation will be added in the next part of this series. We will add more tags to make our simple document more informative and detailed.

In this sample, i have created a C# example, but there is also a plug in for VB.NET, which i will try to discuss in the coming parts.

happy documentation

Color..........its what that makes web what it is

How many of us really spend time on how a page or website looks, we(take me as a very good example) just go search for some nice looking page, use it as a template, make some changes and our website is ready.

Later when the client asks for some change, say the color setting for a particular information on the page, we touch a small part of the page and the whole thing comes crashing down. The whole thing looks a mess. Lots of clashing, contrasting patterns of color. It looks more like a child painting.

I was just browsing when i came across these series of articles or posting in devx
(http://www.devx.com/projectcool/Article/19954) about colors and their importance. I knew some of the basics that this article talks about, but seriously i did not put much though into the design of my pages, these articles were a big help.

Now i spend more time on the color that i use on my pages. I think about the need for a particular page/site and with these requirements in mind and other factors, i am able to get a more integrated look and feel for my pages/sites

Hope others like me learn from these kind of nice, but basic articles...

cheers,

narsim