Page 1 of 1

Adding Documentation & Summaries to your code

#1 jacobjordan  Icon User is offline

  • class Me : Perfection
  • member icon

Reputation: 113
  • View blog
  • Posts: 1,499
  • Joined: 11-June 08

Posted 05 September 2008 - 04:08 PM

*
POPULAR

http://www.dreamincode.net/forums/index.php?act=Attach&type=post&id=8200
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:
/// <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:
/// <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:
/// <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:
/// <!-- This is a comment. -->

It can be applied anywhere. It can even be applied inside summaries like this:
/// <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:
/// <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:
[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:
[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:
[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:
[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.

Attached image(s)

  • Attached Image


Is This A Good Question/Topic? 5
  • +

Replies To: Adding Documentation & Summaries to your code

#2 gbertoli3  Icon User is offline

  • DIC at Heart + Code
  • member icon

Reputation: 40
  • View blog
  • Posts: 1,162
  • Joined: 23-June 08

Posted 05 September 2008 - 06:50 PM

Aww man You Beat Me To It!
I was going to make something like this into a tutorial. Nice :^:
Was This Post Helpful? 0
  • +
  • -

#3 jacobjordan  Icon User is offline

  • class Me : Perfection
  • member icon

Reputation: 113
  • View blog
  • Posts: 1,499
  • Joined: 11-June 08

Posted 05 September 2008 - 07:10 PM

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.
Was This Post Helpful? 0
  • +
  • -

#4 Amadeus  Icon User is offline

  • g+ + -o drink whiskey.cpp
  • member icon

Reputation: 248
  • View blog
  • Posts: 13,507
  • Joined: 12-July 02

Posted 16 September 2008 - 09:58 AM

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.
Was This Post Helpful? 0
  • +
  • -

#5 jacobjordan  Icon User is offline

  • class Me : Perfection
  • member icon

Reputation: 113
  • View blog
  • Posts: 1,499
  • Joined: 11-June 08

Posted 16 September 2008 - 05:57 PM

View PostAmadeus, on 16 Sep, 2008 - 11:58 AM, said:

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.

View PostAmadeus, on 16 Sep, 2008 - 11:58 AM, said:

Secondly, there are several tutorials on this very subject scattered around the internet.
I was only referring to DIC, actually.
Was This Post Helpful? 0
  • +
  • -

#6 sureej19  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 4
  • Joined: 12-June 10

Posted 12 June 2010 - 09:15 AM

Great article. Thanks a lot.

This is one area people like me fail badly.
Was This Post Helpful? 0
  • +
  • -

#7 Guest_saYRam*


Reputation:

Posted 12 January 2011 - 07:26 AM

View Postsureej19, on 12 June 2010 - 08:15 AM, said:

Great article. Thanks a lot.

This is one area people like me fail badly.


well, how to show comments in property tag?

Posted Image
Was This Post Helpful? 0

#8 Michael26  Icon User is offline

  • DIC-head, major DIC-head
  • member icon

Reputation: 362
  • View blog
  • Posts: 1,537
  • Joined: 08-April 09

Posted 19 October 2012 - 06:26 AM

I have class library that contains method for FisherYates Shuffle, using summary i class library works fine, but when i exported the DLL file from class library to another project the comments summary is unavailable.

What i'm doing wrong?

 /// <summary>
        /// Shuffle for List &ltT&gt
        /// </summary>
        /// <typeparam name="T">Type of the List</typeparam>
        /// <param name="List">List to be sorted</param>

This isn't shown here
Posted Image

Found the solution, in the properties of your library in the build menu check the XML documentation file and then rebuild

This post has been edited by Michael26: 19 October 2012 - 06:35 AM

Was This Post Helpful? 0
  • +
  • -

#9 tlhIn`toq  Icon User is offline

  • Please show what you have already tried when asking a question.
  • member icon

Reputation: 5632
  • View blog
  • Posts: 12,080
  • Joined: 02-June 10

Posted 23 December 2012 - 08:01 AM

I like the tutorial and getting people to actually do in-code documentation. It would have been nice to see this extended (or a part 2 tutorial) to include using that XML documentation with something like Doxygen to produce final HTML documentation.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1