Adding Documentation & Summaries to your code Options

[jacobjordan]

Recognize it? It's a Visual Studio description of a function. It is almost mandatory to have these descriptions in your .NET code if you plan to distribute them. We will explain how to do this and how to do property grid tags on properties.

Basic Summaries

Descriptions such as the one above can be applied to classes, functions, structs, enums, variables, and almost anything else. To declare a description, type a special comment (three consecutive forward slashes in C#, which looks like "///") on the line before the function or item you wish to describe. If you are using Visual Studio, which i am assuming you are, it will automatically fill in the rest for you, which should look something like this on a function with no arguments:

csharp

/// <summary>
/// 
/// </summary>
public void Something()
{

}

It has inserted 2 XML tags, which between them you will type the description for your object. That is as basic as it gets. Here is what it would look like on a function which returns int, but takes no arguments:

csharp

/// <summary>
/// 
/// </summary>
/// <returns></returns>
public int Something()
{

}

Notice it has put another set of tags, the "return" tags. Between them you can describe what the functions returns. However, that can easily be incorporated into the summary, so it really doesn't serve a practical purpose. Now, let's try this on a function that takes an argument and returns a value:

csharp

/// <summary>
/// 
/// </summary>
/// <param name="SomethingElse"></param>
/// <returns></returns>
public int Something(int SomethingElse)
{

}

Notice another tag has been added. It is "param name="SomethingElse"". Inside that tag you can give a description for an argument ("SomethingElse", in this case).

Another useful tag is a comment tag. It looks like an HTML comment and is used like this:

csharp

/// <!-- This is a comment. -->

It can be applied anywhere. It can even be applied inside summaries like this:

csharp

/// <summary> This is a <!-- Comment -->summary. </summary>

Now, there is one more tag we need to discuss. It is the "remarks" tag. It can be applied to anything, and is used to add extra description to an object. It does not show up in a Visual Studio summary box, and is purely for someone who might be reading your code. For the sake of going all-out, here is a very complicated summary:

csharp

/// <summary> This is a <!-- Comment -->summary. </summary>
/// <summary>
/// Does nothing at all you would be concerned with.
/// Is only ment to be an example for XML documentation
/// in C# code.
/// </summary>
/// <!-- This is a comment. -->
/// <param name="SomethingElse">Description for the "SomethingElse" param</param>
/// <param name="AnotherThing">Description <!-- Comment --> for the "AnotherThing" param</param>
/// <param name="SomePointer">Description for the "SomePointer" param</param>
/// <returns>Description for what the function returns</returns>
/// <remarks>Text put here will not display in a Visual Studio summary box.
/// It is ment to add in further detail for anyone who might read this
/// code in the future
/// </remarks>
public unsafe int* Something(int SomethingElse, string AnotherThing, int* SomePointer)
{
    SomethingElse += AnotherThing.Length;
    *SomePointer = SomethingElse;
    return SomePointer;
}

Property Grid Tags

Anyone who has used the Visual Studio form designer knows that properties can have a default value, are arranged in categories, and have descriptions. These can be done with a simple [...] tag placed in front of said property. To assign a property a default value, this is what it might look like:

csharp

[System.ComponentModel.DefaultValue(0)]
public int AProperty
{
    get
    {
        //Return something
    }
    set
    {
        //Do something
    }
}

That sets that properties default value to zero. Now, to put a property in a category:

csharp

[System.ComponentModel.Category("CategoryName")]
public int AProperty
{
    get
    {
        //Return something
    }
    set
    {
        //Do something
    }
}

That puts that property in a category called "CategoryName". If a category isn't specified on a property, a property grid will automatically place it in a "Misc" category. Now, probably most importantly, to add a description to a property:

csharp

[System.ComponentModel.Description("Description Goes Here")]
public int AProperty
{
    get
    {
        //Return something
    }
    set
    {
        //Do something
    }
}

That will obviously assign that property a description of "Description Goes Here". All three of these items can be placed on one property. However, you would not put three separate [...] blocks in front of the property, as that is not legal. You would put all three items in a single block of brackets, with commas separating them. To add all three items to a property, use:

csharp

[System.ComponentModel.DefaultValue(0),
System.ComponentModel.Category("CategoryName"),
System.ComponentModel.Description("Description Goes Here")]
public int AProperty
{
    get
    {
        //Return something
    }
    set
    {
        //Do something
    }
}

Note that they can all go on one line. I separated them for easy reading.

I have only covered the very basics in this tutorial. Be warned, there may be a part 2 in the future.

[gbertoli3]

Aww man You Beat Me To It!
I was going to make something like this into a tutorial. Nice

[jacobjordan]

To tell you the truth, i'm surprised someone else hadn't done this by now. This is very useful stuff and it makes a killer tutorial, and it took 7 years before someone actually make a tutorial out of it.

[Amadeus]

Actually the .NET language group in it's current inception is not yet 7 years old, so it's not a fair comparison to equate the age of the site with the length of time it took for a tutorial like this to be submitted. Secondly, there are several tutorials on this very subject scattered around the internet.

Your submission is appreciated.

[jacobjordan]

Actually the .NET language group in it's current inception is not yet 7 years old, so it's not a fair comparison to equate the age of the site with the length of time it took for a tutorial like this to be submitted.

me.Idiot = true;

Had a stupid moment there. Forgot how new the .NET framework was.

Secondly, there are several tutorials on this very subject scattered around the internet.

I was only referring to DIC, actually.