C# API 文档注释规范

最近在开发工作中需要实现 API 帮助文档，如果根据所写的代码直接重写 API 帮助文档将会是意见非常大的工作量，如果根据所写的代码直接生成 API 帮助文档，将会大大减少工作量。Sandcastle Help File Builder可以实现上述需求。如果想要生成一个比较全面的 API 帮助文档，就需要对 C# 代码做一个比较全面的注释。在本文中，将根据Sandcastle Help File Builder 文档对 C# 代码注释做一个简单的总结。

1. 命名空间注释(namespace)

XML 注释不能直接应用于代码中的命名空间。因此，必须采取 指定命名空间注释的替代方法。

在源代码中，向每个命名空间添加一个空的 NamespaceDoc 类，当生成 XML 注释文件时，它们将用作命名空间注释。若要防止 NamespaceDoc 类出现在帮助文件中，请省略public关键字，并使用 CompilerGenerated 属性对其进行标记。 这将导致在为程序集生成反射信息时自动忽略该类。 下面是一个示例：

namespace OpenVinoSharp
{
    /// 

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

2. summary

用于提供类型或成员的简要说明，对所有类型和类型成员都有效。格式如下：

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

例如：

/// 

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

在使用Sandcastle Help File Builder生成帮助文档后显示：

3. remarks and para

remarks：用于提供类型或成员的更详细说明，对所有类型和类型成员都有效。格式如下：

parade：用于在其他元素中开始一个新段落。格式如下：

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

例如：

/// 
///     
///     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:
///     
///     ONNX format (*.onnx)
///     PDPD(*.pdmodel)
///     TF(*.pb)
///     TFLite(*.tflite)
/// 
public Model read_model(string model_path, string bin_path = "") 

在使用Sandcastle Help File Builder生成帮助文档后显示：

4. param

用于描述方法参数。对描述每个参数的方法和运算符重载有效。参数名称是被引用的参数的名称。格式如下：

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

例如：

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

在使用Sandcastle Help File Builder生成帮助文档后显示：

5. returns

用于描述方法的返回值，对返回值的所有方法都有效。格式如下：

/// <returns>descriptionreturns>

例如：

/// InferRequest object
public InferRequest create_infer_request()

在使用Sandcastle Help File Builder生成帮助文档后显示：

6. example and code

example： 用于定义类型或其成员之一的示例，以显示如何使用它。对所有类型和成员都有效。说明是可选的。通常包含一个或多个代码元素以显示示例代码，为了更具描述性的文本，可以根据需要包含在代码元素之间。

code：用于指示应将多行文本部分格式化为代码块。格式如下：

/// <example>
/// Optional code description
/// <code language="C#">
/// Example code
/// code>
/// 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:
/// 
/// 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
/// 
/// 
public PreProcessSteps convert_layout(Layout layout)

在使用Sandcastle Help File Builder生成帮助文档后显示：

7. exception

用于列出可由类型成员引发的异常。对属性、方法、事件、运算符和类型转换成员有效。异常类型是可以引发的异常类型的名称。格式如下：

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

例如：

/// If a model has more than one input, this method throws ov::Exception.
public Input input()

在使用Sandcastle Help File Builder生成帮助文档后显示：

8. typeparam

用于描述泛型类型和方法上的泛型参数。对泛型类型和泛型方法有效，用于描述每个泛型类型参数。类型参数名称是泛型类型参数的名称 引用。格式如下：

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

例如：

/// data type
public void set_data(T[] input_data)

在使用Sandcastle Help File Builder生成帮助文档后显示：