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

2. summary

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

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

例如：

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

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

3. remarks and para

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

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

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

例如：

/// <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 = "") 

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

4. param

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

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

例如：

/// <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) 

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

5. returns

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

/// <returns>description</returns>

例如：

/// <returns>InferRequest object</returns>
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>

例如：

/// <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)

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

7. exception

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

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

例如：

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

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

8. typeparam

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

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

例如：

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

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