C# API Documentation Comment Specification

Recently, API help documents need to be implemented in the development work. If the API help documents are directly rewritten according to the written code, it will be a very heavy workload. If the API help documents are directly generated according to the written code, the work will be greatly reduced. quantity. Sandcastle Help File Builder can achieve the above needs. If you want to generate a more comprehensive API help document, you need to make a more comprehensive comment on the C# code. In this article, a brief summary of C# code comments will be made based on the Sandcastle Help File Builder documentation.

1. Namespace annotation (namespace)

XML comments cannot be applied directly to namespaces in code. Therefore, an alternative to specifying namespace annotations must be taken.

In the source code, add an empty class to each namespace NamespaceDoc, and they will be used as namespace annotations when generating XML annotation files. To prevent NamespaceDoc a class from appearing in the help file, omit publicthe keyword and CompilerGenerated mark it with an attribute. This will cause the class to be automatically ignored when generating reflection information for the assembly. Here is an example:

namespace OpenVinoSharp
{
    /// <summary>
    /// These are the namespace comments for <c>OpenVinoSharp</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceDoc
    {
    }
}

2. summary

Used to provide a brief description of a type or member, valid for all types and type members. The format is as follows:

/// <summary>
/// function/claee/enmu description
/// </summary>

For example:

/// <summary>
/// Global functions under ov namespace
/// </summary>
public static partial class Ov
{}

After using the Sandcastle Help File Builder to generate the help file it shows:

3. remarks and para

remarks: Used to provide a more detailed description of a type or member, valid for all types and type members. The format is as follows:

parade: Used to start a new paragraph within other elements. The format is as follows:

/// <remarks>
/// dfunction/claee/enmu description
/// </remarks>

For example:

/// <remarks>
///     <para>
///     For IR format (*.bin):
///     if `bin_path` is empty, will try to read a bin file with the same name as xml and
///     if the bin file with the same name is not found, will load IR without weights.
///     For the following file formats the `bin_path` parameter is not used:
///     </para>
///     <para>ONNX format (*.onnx)</para>
///     <para>PDPD(*.pdmodel)</para>
///     <para>TF(*.pb)</para>
///     <para>TFLite(*.tflite)</para>
/// </remarks>
public Model read_model(string model_path, string bin_path = "") 

After using the Sandcastle Help File Builder to generate the help file it shows:

4. param

Used to describe method parameters. Valid for method and operator overloads describing each argument. parameter_name is the name of the parameter being referenced . The format is as follows:

/// <param name="paramName">
/// Parameter description
/// </param>

For example:

/// <param name="model_path">String with a model in IR / ONNX / PDPD / TF / TFLite format.</param>
/// <param name="weights">Shared pointer to a constant tensor with weights.</param>
public Model read_model(string model_path, Tensor weights) 

After using the Sandcastle Help File Builder to generate the help file it shows:

5. returns

Used to describe the return value of a method, valid for all methods that return a value. The format is as follows:

/// <returns>description</returns>

For example:

/// <returns>InferRequest object</returns>
public InferRequest create_infer_request()

After using the Sandcastle Help File Builder to generate the help file it shows:

6. example and code

example: An example used to define the type or one of its members, to show how to use it. Valid for all types and members. Description is optional. Usually one or more code elements are included to show sample code, and for more descriptive text, can be included between code elements as needed.

code: Used to indicate that a multi-line text section should be formatted as a code block. The format is as follows:

/// <example>
/// Optional code description
/// <code language="C#">
/// Example code
/// </code>
/// </example>

For example:

/// <example>
/// when user data has 'NHWC' layout (example is RGB image, [1, 224, 224, 3]) but model expects
/// planar input image ('NCHW', [1, 3, 224, 224]). Preprocessing may look like this:
/// <code>
/// var proc = PrePostProcessor(model);
/// proc.input().tensor().set_layout("NHWC"); // User data is NHWC
/// proc.input().preprocess().convert_layout("NCHW")) // model expects input as NCHW
/// </code>
/// </example>
public PreProcessSteps convert_layout(Layout layout)

After using the Sandcastle Help File Builder to generate the help file it shows:

7. exception

Used to list exceptions that can be thrown by members of a type. Valid for properties, methods, events, operators, and type conversion members. exception_type is the name of the type of exception that can be raised . The format is as follows:

/// <exception cref="exceptionType">description</exception>

For example:

/// <exception cref="">If a model has more than one input, this method throws ov::Exception.</exception>
public Input input()

After using the Sandcastle Help File Builder to generate the help file it shows:

8. typeparam

Used to describe generic parameters on generic types and methods. Valid for generic types and generic methods, used to describe each generic type parameter. A type parameter name is a reference to the name of a generic type parameter. The format is as follows:

/// <typeparam name="T">Type parameter description</typeparam>

For example:

/// <typeparam name="T">data type</typeparam>
public void set_data<T>(T[] input_data)

After using the Sandcastle Help File Builder to generate the help file it shows: