最近在开发工作中需要实现 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生成帮助文档后显示：文章来源：https://www.toymoban.com/news/detail-653077.html
文章来源地址https://www.toymoban.com/news/detail-653077.html
到了这里，关于C# API 文档注释规范的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！
