Skip to content

Documentation Samples

In the previous level of programming, you learned the importance of documenting classes and class members. In this course, the documentation will look different, but the purpose and process is the same.

Use the following examples as reference for the work you will do in this course.

Note

The implementation of the methods and properties have been omitted on purpose.

Class

Things to take note of:

  • The class is documented.
  • Fields are not documented.
  • Documentation is completed using XML style documentation.
  • All XML elements contain information about the class or class member.
C#
using System;

namespace ADEV.Documentation.Samples
{
    /// <summary>
    /// Represents a Person.
    /// </summary>
    public class Person
    {
        private string name;
        private decimal amountOfMoney;

        /// <summary>
        /// Gets the Person's name.
        /// </summary>
        public string Name
        {

        }

        /// <summary>
        /// Gets and sets the amount of money the Person has.
        /// </summary>
        public decimal AmountOfMoney
        {

        }

        /// <summary>
        /// Initializes an instance of the Person class with the specified name and amount of money.
        /// </summary>
        /// <param name="name">The Person's name.</param>
        /// <param name="amount">The amount of money the Person has.</param>
        public Person(string name, decimal amount)
        {

        }

        /// <summary>
        /// Initializes an instance of the Person class with the specified name and no money.
        /// </summary>
        /// <param name="name">The Person's name.</param>
        public Person(string name) : this(name, 0)
        {

        }

        /// <summary>
        /// Adds the specified amount to the Person's amount of money.
        /// </summary>
        /// <param name="amount">The amount of money to be added.</param>
        public void AddMoney(decimal amount)
        {

        }

        /// <summary>
        /// Subtracts the specified amount from the Person's amount of money.
        /// </summary>
        /// <param name="amount">The amount of money to be subtracted.</param>
        public void SubtractMoney(decimal amount)
        {

        }

        /// <summary>
        /// Returns the String representation of a Person.
        /// </summary>
        /// <returns>The String representation of a Person.</returns>
        public override string ToString()
        {

        }
    }
}

Enumeration

Things to take note of:

  • The enumeration is documented.
  • Each enumeration value is documented.
  • Documentation is completed using XML style documentation.
  • All XML elements contain information about the class or class member.
C#
using System;

namespace ADEV.Documentation.Samples
{
    /// <summary>
    /// Specifies the gears for a passenger vehicle.
    /// </summary>
    public enum VehicleGear
    {
        /// <summary>
        /// The neutral gear.
        /// </summary>
        Neutral,

        /// <summary>
        /// The first gear.
        /// </summary>
        First,

        /// <summary>
        /// The second gear.
        /// </summary>
        Second,

        /// <summary>
        /// The third gear.
        /// </summary>
        Third,

        /// <summary>
        /// The fouth gear.
        /// </summary>
        Fourth,

        /// <summary>
        /// The fifth gear.
        /// </summary>
        Fifth,

        /// <summary>
        /// The sixth gear.
        /// </summary>
        Sixth
    }
}

Exceptions

When a class member has the potential to generate an exception, details about that must be included in the class member's documentation. Unlike most other elements of the XML documentation, the <exception> will not likely be auto-generated for you. You will need to manually code this into the documentation.

Things to take note of:

  • Documentation is completed using XML style documentation.
  • You must include one instance of the <exception>...</exception> element per exception type generated by the class member.

Sample 1

In the sample code below, you can see an example of documentation that includes information about an exception that is generated in the unit. The exception in the sample is of type System.ArgumentOutOfRangeException. An example of the possible text within the <exception> element would be: "Thrown when the amount is less than zero."

C#
/// <summary>
/// ...
/// </summary>
/// <param name="amount">...</param>
/// <exception cref="System.ArgumentOutOfRangeException">Thrown when...</exception>
public void Bar(int amount)
{
    // Implementation omitted from the sample
}

Sample 2

In this sample code, the exception type System.ArgumentOutOfRangeException is generated in more than one situation with different parameters. You can see that the documentation still only includes one exception element, but the description includes the various situations when that exception type is thrown. An example of the possible text within the <exception> element would be: "Thrown when the amount is less than zero or the tip is less than or equal to zero."

C#
/// <summary>
/// ...
/// </summary>
/// <param name="amount">...</param>
/// <param name="tip">...</param>
/// <returns>...</returns>
/// <exception cref="System.ArgumentOutOfRangeException">Thrown when amount is ... or when tip is ...</exception>
public int Bar(int amount, decimal tip)
{
    // Implementation omitted from the sample
}

Sample 3

In this sample code, the unit generates two types of exceptions. Therefore, the documentation will include one exception element per type of exception that is generated.

C#
/// <summary>
/// ...
/// </summary>
/// <param name="description">...</param>
/// <param name="amount">...</param>
/// <exception cref="System.FormatException">Thrown when...</exception>
/// <exception cref="System.ArgumentOutOfRangeException">Thrown when...</exception>
public void Bar(String description, int amount)
{
    // Implementation omitted from the sample
}

Note

The documentation of a method or property will contain one <exception> element for each type of exception thrown. Do not include an <exception> element for each throw of an exception of the same type.

For example, if a method generates an ArgumentOutOfRangeException when one parameter is less than zero and an ArgumentOutOfRangeException when another parameter is less than zero, the method would only include one <exception> element with an explanation of the two possible ways the exception could happen.

Events

Things to take note of:

  • The event is documented and explains when the event takes place.
  • Documentation is completed using XML style documentation.
  • All XML elements contain information about the class or class member.
C#
using System;

namespace ADEV.Documentation.Samples
{
    public class Student
    {
        /// <summary>
        /// Occurs when the Student's test average falls below the standard.
        /// </summary>
        public event EventHandler AverageBelowFail;

        /// <summary>
        /// Raises the AverageBelowFail event.
        /// </summary>
        protected virtual void OnAverageBelowFail()
        {
            if (AverageBelowFail != null)
            {
                AverageBelowFail(this, EventArgs.Empty);
            }
        }
    }
}

Event Handler Methods

Things to take note of:

  • The event handler method is documented and explains what event(s) it handles and which objects those events are for.
  • The auto-generated parameters are removed.
  • All XML elements contain information about the class or class member.
C#
// <summary>
/// Handles the AverageBelowFail event of a Student.
/// </summary>
static void Student_AverageBelowFail(object sender, EventArgs e)
{

}