网站备案名称中国开头,郑州怎么做外贸公司网站,网站是哪个公司做的好,孩子学编程最佳年龄C# API 文档注释规范 1. 命名空间注释(namespace)2. summary3. remarks and para4. param5. returns6. example and code7. exception8. typeparam 最近在开发工作中需要实现 API 帮助文档#xff0c;如果根据所写的代码直接重写 API 帮助文档将会是意见非常大的工作量#x… C# API 文档注释规范 1. 命名空间注释(namespace)2. summary3. remarks and para4. param5. returns6. example and code7. exception8. typeparam 最近在开发工作中需要实现 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 cOpenVinoSharp/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
/// paraONNX format (*.onnx)/para
/// paraPDPD(*.pdmodel)/para
/// paraTF(*.pb)/para
/// paraTFLite(*.tflite)/para
/// /remarks
public Model read_model(string model_path, string bin_path ) 在使用Sandcastle Help File Builder生成帮助文档后显示 4. param
用于描述方法参数。对描述每个参数的方法和运算符重载有效。参数名称是被引用的参数的名称。格式如下
/// param nameparamName
/// Parameter description
/// /param例如
/// param namemodel_pathString with a model in IR / ONNX / PDPD / TF / TFLite format./param
/// param nameweightsShared pointer to a constant tensor with weights./param
public Model read_model(string model_path, Tensor weights) 在使用Sandcastle Help File Builder生成帮助文档后显示 5. returns
用于描述方法的返回值对返回值的所有方法都有效。格式如下
/// returnsdescription/returns例如
/// returnsInferRequest object/returns
public InferRequest create_infer_request()在使用Sandcastle Help File Builder生成帮助文档后显示 6. example and code
example 用于定义类型或其成员之一的示例以显示如何使用它。对所有类型和成员都有效。说明是可选的。通常包含一个或多个代码元素以显示示例代码为了更具描述性的文本可以根据需要包含在代码元素之间。
code用于指示应将多行文本部分格式化为代码块。格式如下
/// example
/// Optional code description
/// code languageC#
/// 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 crefexceptionTypedescription/exception例如
/// exception crefIf a model has more than one input, this method throws ov::Exception./exception
public Input input()在使用Sandcastle Help File Builder生成帮助文档后显示 8. typeparam
用于描述泛型类型和方法上的泛型参数。对泛型类型和泛型方法有效用于描述每个泛型类型参数。类型参数名称是泛型类型参数的名称 引用。格式如下
/// typeparam nameTType parameter description/typeparam例如
/// typeparam nameTdata type/typeparam
public void set_dataT(T[] input_data)在使用Sandcastle Help File Builder生成帮助文档后显示
