#325 – Intellisense Understands Generic Classes

When using a generic class, Intellisense understands the type parameters passed to the class when it was constructed.  It will display the correct types when showing information for any method or property of the generic class.

Suppose we have a generic class defined as follows:

    public class ThingContainer<TThing1, TThing2>
    {
        private TThing1 thing1;
        private TThing2 thing2;

        public void SetThings(TThing1 first, TThing2 second)
        {
            thing1 = first;
            thing2 = second;
        }
    }

And suppose that we use the class as follows:

            ThingContainer<Dog, DateTime> container = new ThingContainer<Dog, DateTime>();

Now when we start entering the name of the ThingContainer.SetThings method, Intellisense displays the correct types for the method’s parameters.

Advertisements

#302 – Generating an XML Documentation File

You can use XML Documentation in a class that you author, to provide documentation for the class and its members.

The compiler to generate a separate XML file containing all of your XML Documentation if you do the following:

  • Right-click your Project and select Properties
  • On the Build tab, check the XML documentation file option

If you open the XML file that is generated, you’ll see XML tags containing all of your XML Documentation.

You can use this XML file to automatically generate documentation for your class, with a custom tool or a tool like Sandcastle.

You can also distribute an XML documentation file, along with a binary DLL (e.g. class library).  If the XML documentation file is present, code that references the types in the DLL will be able to display the Intellisense for the types in the DLL.

#301 – Using XML Documentation at the Class Level

In addition to adding context to Intellisense for method calls, XML Documentation can be used to provide Intellisense context for a class itself.

You add XML Documentation to a class by entering “///” on a blank line immediately preceding the class keyword.  Visual Studio will create an empty template for you to fill in.

    /// <summary>
    ///
    /// </summary>
    public class Dog
    {

To finish the documentation, enter a short description of the purpose of the class, within the <summary> tags.

    /// <summary>
    /// Represents a Dog, one of our furry friends.  Dogs can
    /// bark and do basic chores like fetching your newspaper.
    /// </summary>
    public class Dog
    {

If a class has XML Documentation at the class level, Intellisense will display that information when you enter the name of the class in your code.

#300 – Use XML Documentation to Inform Intellisense

Intellisense in Visual Studio 2010 is a very powerful tool.  Among other things, it gives someone coding against a class additional information about a particular method and its parameters.

In the example below, we’ve just typed the opening parenthesis after the name of the Bark method.  An Intellisense window pops up and tells us about the method and its parameter.

To support Intellisense, you need to add XML documentation to your method.  To start with, enter “///” on a blank line immediately preceding the first line of your method.  Visual Studio will create an empty template for you to fill in.

        /// <summary>
        ///
        /// </summary>
        /// <param name="numTimes"></param>
        public void Bark(int numTimes)

To finish the documentation, just enter a short description of the method within the <summary> tag and a description of each parameter within the <param> tags.

#299 – Intellisense Shows You Available Constructors

If you have several different constructors define for a class or a struct, Intellisense in Visual Studio will show you the different constructors that you can use.

Assume that you have a Dog class, with two different constructors, as follows:

    public class Dog
    {
        public string Name { get; set; }
        public int Age { get; set; }

        public Dog(string name, int age)
        {
            Name = name;
            Age = age;
        }

        public Dog(string name)
            : this(name, 1)
        {
        }
    }

Because we have these two constructors, we can pass in either one or two parameters when using the new operator to construct a new instance of a Dog.

            Dog d1 = new Dog("Lassie");
            Dog d2 = new Dog("Django", 6);

Visual Studio will tell us, through Intellisense, that there are two constructors available.  Once the constructor signature pops up, you can use the arrow keys to cycle through the two options.