#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

Filed under Exceptions Tagged with , , ,

#829 – Add Comments to Indicate Shallow vs. Deep Copying

April 24, 2013 2 Comments

When you include a copy constructor or Clone method in your class, you should let users of your code know whether these operations are doing shallow or deep copies.

You can indicate whether the copy operation is shallow or deep using XML Documentation Comments.  These comments will then be exposed to Intellisense and within the Object Browser in Visual Studio.  (Provided that you have access to the source code).

For example:

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

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

        /// <summary>
        /// Make a (deep) copy of specified Dog
        /// </summary>
        /// <param name="otherDog">Dog to copy</param>
        public Dog(Dog otherDog)
        {
            Name = otherDog.Name;
            Age = otherDog.Age;
            Collar = new DogCollar(otherDog.Collar);
        }
    }

Intellisense will now show this comment:
829-001
As will the Object Browser:

829-002

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 , , ,

#300 – Use XML Documentation to Inform Intellisense

April 13, 2011 1 Comment

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.

Filed under Visual Studio Tagged with , , , , ,