C# API 文档注释规范

C# API 文档注释规范

  • [1. 命名空间注释(namespace)](#1. 命名空间注释(namespace))
  • [2. summary](#2. summary)
  • [3. remarks and para](#3. remarks and para)
  • [4. param](#4. param)
  • [5. returns](#5. returns)
  • [6. example and code](#6. example and code)
  • [7. exception](#7. exception)
  • [8. typeparam](#8. typeparam)

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

1. 命名空间注释(namespace)

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

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

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

2. summary

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

xml 复制代码
/// <summary>
/// function/claee/enmu description
/// </summary>

例如:

C# 复制代码
/// <summary>
/// Global functions under ov namespace
/// </summary>
public static partial class Ov
{}

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

3. remarks and para

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

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

xml 复制代码
/// <remarks>
/// dfunction/claee/enmu description
/// </remarks>

例如:

c# 复制代码
/// <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

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

xml 复制代码
/// <param name="paramName">
/// Parameter description
/// </param>

例如:

c# 复制代码
/// <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

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

xml 复制代码
/// <returns>description</returns>

例如:

C# 复制代码
/// <returns>InferRequest object</returns>
public InferRequest create_infer_request()

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

6. example and code

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

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

xml 复制代码
/// <example>
/// Optional code description
/// <code language="C#">
/// Example code
/// </code>
/// </example>

例如:

C# 复制代码
/// <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

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

xml 复制代码
/// <exception cref="exceptionType">description</exception>

例如:

C# 复制代码
/// <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

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

xml 复制代码
/// <typeparam name="T">Type parameter description</typeparam>

例如:

c# 复制代码
/// <typeparam name="T">data type</typeparam>
public void set_data<T>(T[] input_data)

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

相关推荐
何曾参静谧几秒前
「C/C++」C/C++ 之 变量作用域详解
c语言·开发语言·c++
q5673152327 分钟前
在 Bash 中获取 Python 模块变量列
开发语言·python·bash
许野平1 小时前
Rust: 利用 chrono 库实现日期和字符串互相转换
开发语言·后端·rust·字符串·转换·日期·chrono
也无晴也无风雨1 小时前
在JS中, 0 == [0] 吗
开发语言·javascript
狂奔solar1 小时前
yelp数据集上识别潜在的热门商家
开发语言·python
blammmp2 小时前
Java:数据结构-枚举
java·开发语言·数据结构
何曾参静谧2 小时前
「C/C++」C/C++ 指针篇 之 指针运算
c语言·开发语言·c++
暗黑起源喵2 小时前
设计模式-工厂设计模式
java·开发语言·设计模式
WaaTong2 小时前
Java反射
java·开发语言·反射
Troc_wangpeng2 小时前
R language 关于二维平面直角坐标系的制作
开发语言·机器学习