Related Jira Issues

Introduction

The following documentation defines the means by which code will be commented and the types of documentation that will be produced. It should be noted that the Programming Style Guide contains its own guide to general commenting practice. Should this document and the Style Guide conflict when it pertains to commenting code, this document will take precedence. Please notify the Project Lead of any discrepancies between this document and the Style Guide so that they may be addressed.

...

• When building a public method:

  • A <summary> tag will be written to describe the purpose for the method

  • A <param> tag will be written to describe each parameter within the public function
    

    Code Block
    /// <param name="left"> /// The left operand of the addition. /// </param> /// <param name="right"> /// The right operand of the addition. /// </param> public static int Add(int left, int right) { if ((left == int.MaxValue && right > 0) || (right == int.MaxValue && left > 0)) throw new System.OverflowException(); return left + right; }

  • A <returns> tag will be used to describe the return value of the method where applicable

    • Use common language when describing return values.
      ❌

      Code Block
      <returns>Returns an int</returns> public int GetAverage(int x, int y) { return (x+y)/2; }

      ✅

      Code Block
      <returns>Returns the average of two integers</returns> public int GetAverage(int x, int y) { return (x+y)/2; }

• When building a private method, no <summary> tagged comment is required. However, it is highly recommended that a generageneral, l non-xml tag be at least written to describe the nature of a private method should it’s purpose not be immediately apparent.

• If a method (public or private) can throw an exception, the exception tag will be used to document what types of exceptions the method can be expected to throw
  

  Code Block

  /// <exception cref="System.OverflowException"> /// Thrown when one parameter is max and the other /// is greater than 0.</exception> public static double Add(double a, double b) { // If any parameter is equal to the max value of an integer // and the other is greater than zero if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) { throw new System.OverflowException(); } return a + b; }

...

/// <example>
/// <code>
/// int c = Math.Add(4, 5);
/// if (c > 10)
/// {
///     Console.WriteLine(c);
/// }
/// </code>
/// </example>
public static int Add(int left, int right)
{
    if ((left == int.MaxValue && right > 0) || (right == int.MaxValue && left > 0))
        throw new System.OverflowException();

    return left + right;
}

Documentation

• Any public facing classes will have an associated Class Diagram to outline its general makeup

• Public facing classes within the Communications API will have sequence diagrams built to outline the general flow of communication between the device and the SDK

• Documentation describing the general usage of the SDK will be provided

• Documentation describing the makeup of the Unity example scene will be provided

• Documentation describing how users can make use of the VictoR SDK Unity package will be provided

• Documentation generated from the xmldoc comments will be provided

• Code samples will be written to assist users with familiarizing themselves with the SDK