#913 – How to Document that a Method Can Throw an Exception

August 21, 2013 3 Comments

You can use XML Documentation to document the fact that a method can throw an exception.  You use the Exception tag to indicate the type of exception that can be thrown.  You can also provide a comment related to the exception, which will show up in an XML Documentation file that you generate.

        /// <summary>
        /// Print somebody's name
        /// </summary>
        /// <param name="name">Name to be printed</param>
        /// <exception cref="ApplicationException">Will throw exception if name is Mortimer</exception>
        /// <exception cref="JustBecauseException">I throw this exception on Tuesdays</exception>
        static void PrintMyName(string name)
        {
            if (name.ToLower().Equals("mortimer"))
                throw new ApplicationException("I don't like the name Mortimer");

            if (DateTime.Now.DayOfWeek == DayOfWeek.Tuesday)
                throw new JustBecauseException("Tuesday is my day off");

            Console.WriteLine(string.Format("Your name is {0}", name));
        }

Intellisense will now include a list of the exceptions that might be thrown, when displaying the method’s name.
913-001

 

If you generate a XML Documentation file, it will also include this information.

913-002

Advertisement

Filed under Exceptions Tagged with , , ,

#912 – Intellisense Can Show Exceptions that a Method Might Throw

August 20, 2013 3 Comments

In some cases, when the Intellisense function within Visual Studio shows you information about a method that you are going to call, it will also list potential exceptions that the method might throw.

In the example below, we see that the Matrix.Invert method can throw an exception of type InvalidOperationException.

912-001

 

It’s not the case that every single method that you might call in the Base Class Library (BCL) will provide this information.  Some methods will list the exceptions that they might throw, but many will not.

Filed under Exceptions Tagged with , , ,

#770 – Use Intellisense to Get List of Methods to Override

January 31, 2013 1 Comment

In a derived class, you can override a member of the base class if it’s declared as virtual.  In Visual Studio, the Intellisense feature can help you to discover the methods that can be overridden.

Suppose that we have the following definition for Dog:

    public class Dog
    {
        public virtual string Prop1 { get; set; }
        public string Prop2 { get; set; }

        public virtual void Method1()
        {
            Console.WriteLine("Dog.Method1");
        }

        public void Method2()
        {
            Console.WriteLine("Dog.Method2");
        }
    }

Now when we are adding code to a child class of Dog, we can just enter the keyword override, followed by a space, to see a list of candidate members that can be overridden.

770-001

To add the code for one of these members, just use the down arrow to select the method and then press TAB.  The body of the method will be generated for you.

770-002

Filed under Visual Studio Tagged with , , ,

#691 – Use the this Keyword to Trigger Intellisense

October 12, 2012 Leave a comment

Another use of the this keyword, which refers to the current instance of a class, is to trigger Intellisense in Visual Studio so that you can  see a list of members in the class.

For example, let’s say that you’re writing some code for the Bark method in a Dog class.  You want to call another method in the Dog class, but you can’t remember its name.  You can just type this and a period (.).  After typing the period, an Intellisense window will pop up to show you the members in the Dog class.

You can then select the method that you want to call and Intellisense will remind you of what parameters are required.

Filed under Visual Studio Tagged with , , , ,

#595 – Intellisense Shows Method Overloads

May 31, 2012 5 Comments

When you overload a method, you’re creating multiple methods with the same name, but a different number of parameters, or parameters of different types.  At compile-time, the compiler will automatically call the correct method.

Visual Studio can help with entering parameter values.  When you enter the name of a method, Intellisense shows you a list of available methods with that name.

Let’s say that we have three different versions of a Dog.Bark method.  After typing “Bark” and the opening parenthesis “(“, Intellisense will indicate that there are three versions of the method available and provide information about the first version.

At this point, you can press the up/down arrow keys to cycle through the three different methods.

Notice that Intellisense does the following:

  • Indicates in bold the next parameter that you should enter
  • Lists a description of the method, if one is available
  • Provides a description of the next parameter

Filed under Visual Studio Tagged with , , , ,

#591 – How Optional Parameters Look with Intellisense

May 25, 2012 Leave a comment

When you’re working in Visual Studio and you start typing in the name of a method, Intellisense will show you any optional parameters that the method has.

In the example below, we’ve started entering code to create a new instance of a Dog object.  Intellisense shows us a list of the optional parameters that are defined for the constructor.

Filed under Visual Studio Tagged with , , ,

#439 – Use Visual Studio to Implement an Interface

October 24, 2011 Leave a comment

You can use smart tags in Visual Studio to quickly implement an interface for a class.

For example, let’s say that you want to add code to the Cow class to implement the IMoo interface.  You start by updating the class declaration to derive from IMoo.

If you now hover over the little underline under IMoo, you’ll see a smart tag.

If you click on the smart tag, you’ll see two options.

Click on “Implement interface ‘iMoo’ “.  Empty implementations of all of the interface’s members will be automatically added to the class.  (Note that the methods throw NotImplementedException exceptions by default).

 

Filed under Visual Studio Tagged with , , ,

#325 – Intellisense Understands Generic Classes

May 16, 2011 Leave a comment

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.

Filed under Classes Tagged with , , ,

#302 – Generating an XML Documentation File

April 15, 2011 1 Comment

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.

Filed under Visual Studio Tagged with , , ,

#301 – Using XML Documentation at the Class Level

April 14, 2011 Leave a comment

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.

Filed under Visual Studio Tagged with , , ,

← Older posts