当前位置: 首页 > news >正文

C# API 文档注释规范

C# API 文档注释规范

  • 1. 命名空间注释(namespace)
  • 2. summary
  • 3. remarks and para
  • 4. param
  • 5. returns
  • 6. example and code
  • 7. exception
  • 8. 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 <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生成帮助文档后显示:

image-20230816160129528

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生成帮助文档后显示:

image-20230816162809573

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生成帮助文档后显示:

image-20230816161147746

5. returns

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

/// <returns>description</returns>

例如:

/// <returns>InferRequest object</returns>
public InferRequest create_infer_request()

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

image-20230816161706400

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生成帮助文档后显示:

image-20230816162256142

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生成帮助文档后显示:

image-20230816163642151

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生成帮助文档后显示:

image-20230816165907570

相关文章:

C# API 文档注释规范

C# API 文档注释规范 1. 命名空间注释(namespace)2. summary3. remarks and para4. param5. returns6. example and code7. exception8. typeparam 最近在开发工作中需要实现 API 帮助文档&#xff0c;如果根据所写的代码直接重写 API 帮助文档将会是意见非常大的工作量&#x…...

分类预测 | Matlab实现基于TSOA-CNN-GRU-Attention的数据分类预测

分类预测 | Matlab实现基于TSOA-CNN-GRU-Attention的数据分类预测 目录 分类预测 | Matlab实现基于TSOA-CNN-GRU-Attention的数据分类预测效果一览基本介绍研究内容程序设计参考资料 效果一览 基本介绍 Matlab实现分类预测 | Matlab实现基于TSOA-CNN-GRU-Attention的数据分类预…...

《深度剖析K8s》学习笔记

一、容器技术 1.从进程说起 a. 概述 进程&#xff1a;数据和状态的综合 容器技术的核心&#xff1a;约束和修改进程的动态表现&#xff0c;创造出边界&#xff08;Cgroup&#xff1a;约束/namespace&#xff1a;进程视图&#xff09; 启动容器例子&#xff1a; docker ru…...

神经网络基础-神经网络补充概念-49-adam优化算法

概念 Adam&#xff08;Adaptive Moment Estimation&#xff09;是一种优化算法&#xff0c;结合了动量梯度下降法和RMSProp的优点&#xff0c;用于在训练神经网络等深度学习模型时自适应地调整学习率。Adam算法在深度学习中广泛应用&#xff0c;通常能够加速收敛并提高模型性能…...

Java:正则表达式书写规则及相关案例:检验QQ号码,校验手机号码,邮箱格式,当前时间

正则表达式 目标:体验一下使用正则表达式来校验数据格式的合法性。需求:校验QQ号码是否正确&#xff0c;要求全部是数字&#xff0c;长度是(6-20&#xff09;之间&#xff0c;不能以0开头 首先用自己编写的程序判断QQ号码是否正确 public static void main(String[] args) {Sy…...

图数据库_Neo4j_Centos7.9安装Neo4j社区版3.5.4_基于jdk1.8---Neo4j图数据库工作笔记0011

首先上传安装包,到opt/soft目录 然后看一下jdk安装的是什么版本的,因为在neo4j 4以后就必须要用jdk11 以上的版本,我这里还用着jdk1.8 所以 我这里用3.5.4的版本 关于下载地址: https://dist.neo4j.org/neo4j-community-3.5.4-unix.tar.gz 然后再去解压到/opt/module目录下 …...

使用Rust编写的一款使用遗传算法、神经网络、WASM技术的模拟生物进化的程序

模拟生物进化程序 Github地址&#xff1a;FishLife 期待各位的star✨✨✨ 本项目是一个模拟生物进化的程序&#xff0c;利用遗传算法、神经网络技术对鱼的眼睛和大脑进行模拟。该项目是使用 Rust 语言编写的&#xff0c;并编译为 WebAssembly (Wasm) 格式&#xff0c;使其可以…...

UE4/UE5 “无法双击打开.uproject 点击无反应“解决

一、方法一&#xff1a;运行UnrealVersionSelector.exe 1.找到Epic Game Lancher的安装目录&#xff0c; 在lancher->Engine->Binaries->Win64->UnrealVersionSelector.exe 2.把UnrealVersionSelector.exe 分别拷贝到UE4 不同版本引擎的 Engine->Binaries->…...

【前端】深入理解CSS定位

目录 一、前言二、定位组成1、定位模式1.1、静态定位static①、语法定义②、特点 1.2、相对定位relative①、语法定义②、特点③、代码示例 1.3、绝对定位absolute①、语法定义②、特点③、代码示例1&#xff09;、没有祖先元素或者祖先元素没有定位2&#xff09;、祖先元素有定…...

【问题】分布式事务的场景下如何保证读写分离的数据一致性

我的理解这个题目可以获得以下关键字&#xff1a;分布式处理、读写分离、数据一致性 那么就从”读写分离“做切入口吧&#xff0c;按我的理解其实就是在保证数据一致性的前提下两个&#xff08;或以上&#xff09;的数据库分别肩负不同的数据处理任务。太过久远的就不说了&…...

常见的Web安全漏洞有哪些,Web安全漏洞常用测试方法介绍

Web安全漏洞是指在Web应用程序中存在的可能被攻击者利用的漏洞&#xff0c;正确认识和了解这些漏洞对于Web应用程序的开发和测试至关重要。 一、常见的Web安全漏洞类型&#xff1a; 1、跨站脚本攻击(Cross-Site Scripting&#xff0c;XSS)&#xff1a;攻击者通过向Web页面注入…...

随机微分方程

应用随机过程|第7章 随机微分方程 见知乎&#xff1a;https://zhuanlan.zhihu.com/p/348366892?utm_sourceqq&utm_mediumsocial&utm_oi1315073218793488384...

下载安装并使用小乌龟TortoiseGit

1、下载TortoiseGit安装包 官网&#xff1a;Download – TortoiseGit – Windows Shell Interface to Githttps://tortoisegit.org/download/ 2、小乌龟汉化包 在官网的下面就有官方提供的下载包 3、安装...

npm ERR!Cannot read properties of null(reading ‘pickAlgorithm’)报错问题解决

当在使用npm包管理器或执行npm命令时&#xff0c;有时候会遇到“npm ERR!Cannot read properties of null(reading ‘pickAlgorithm’)”这个错误提示&#xff0c;这是一个常见的npm错误。 这个错误提示通常说明在使用npm包管理器时&#xff0c;执行了某个npm命令&#xff0c;…...

web前端tips:js继承——组合继承

上篇文章给大家分享了 js继承中的借用构造函数继承 web前端tips&#xff1a;js继承——借用构造函数继承 在借用构造函数继承中&#xff0c;我提到了它的缺点 无法继承父类原型链上的方法和属性&#xff0c;只能继承父类构造函数中的属性和方法 父类的方法无法复用&#xff0…...

(7)(7.3) 自动任务中的相机控制

文章目录 前言 7.3.1 概述 7.3.2 自动任务类型 7.3.3 创建合成图像 前言 本文介绍 ArduPilot 的相机和云台命令&#xff0c;并说明如何在 Mission Planner 中使用这些命令来定义相机勘测任务。这些说明假定已经连接并配置了相机触发器和云台(camera trigger and gimbal hav…...

Python 爬虫小练

Python 爬虫小练 获取贝壳网数据 使用到的模块 标准库 Python3 标准库列表 os 模块&#xff1a;os 模块提供了许多与操作系统交互的函数&#xff0c;例如创建、移动和删除文件和目录&#xff0c;以及访问环境变量等。math 模块&#xff1a;math 模块提供了数学函数&#xf…...

vue3 事件处理 @click

在Vue 3中&#xff0c;事件处理可以通过click指令来实现。click指令用于监听元素的点击事件&#xff0c;并在触发时执行相应的处理函数。 下面是一个简单的示例&#xff0c;展示了如何在Vue 3中处理点击事件&#xff1a; <template><button click"handleClick&…...

【第三阶段】kotlin语言使用replace完成加解密操作

fun main() {val password"ASDAFWEFWVWGEGSDFWEFEWGFS"println("原始密码&#xff1a;$password")//加密操作,就是把字符替换成数字&#xff0c;打乱加密var newPsdpassword.replace(Regex("[ADWF]")){when(it.value){//it.value 这里的每一个字…...

springBoot是如何实现自动装配的

目录 1 什么是自动装配 2 Spring自动装配原理 2.1 SpringBootConfiguration ​编辑 2.2 EnableAutoConfiguration 2.2.1 AutoConfigurationPackage 2.2.2 Import({AutoConfigurationImportSelector.class}) 2.3 ComponentScan 1 什么是自动装配 自动装配就是将官方写好的的…...

【HarmonyOS 5.0】DevEco Testing:鸿蒙应用质量保障的终极武器

——全方位测试解决方案与代码实战 一、工具定位与核心能力 DevEco Testing是HarmonyOS官方推出的​​一体化测试平台​​&#xff0c;覆盖应用全生命周期测试需求&#xff0c;主要提供五大核心能力&#xff1a; ​​测试类型​​​​检测目标​​​​关键指标​​功能体验基…...

华硕a豆14 Air香氛版,美学与科技的馨香融合

在快节奏的现代生活中&#xff0c;我们渴望一个能激发创想、愉悦感官的工作与生活伙伴&#xff0c;它不仅是冰冷的科技工具&#xff0c;更能触动我们内心深处的细腻情感。正是在这样的期许下&#xff0c;华硕a豆14 Air香氛版翩然而至&#xff0c;它以一种前所未有的方式&#x…...

视觉slam十四讲实践部分记录——ch2、ch3

ch2 一、使用g++编译.cpp为可执行文件并运行(P30) g++ helloSLAM.cpp ./a.out运行 二、使用cmake编译 mkdir build cd build cmake .. makeCMakeCache.txt 文件仍然指向旧的目录。这表明在源代码目录中可能还存在旧的 CMakeCache.txt 文件,或者在构建过程中仍然引用了旧的路…...

接口自动化测试:HttpRunner基础

相关文档 HttpRunner V3.x中文文档 HttpRunner 用户指南 使用HttpRunner 3.x实现接口自动化测试 HttpRunner介绍 HttpRunner 是一个开源的 API 测试工具&#xff0c;支持 HTTP(S)/HTTP2/WebSocket/RPC 等网络协议&#xff0c;涵盖接口测试、性能测试、数字体验监测等测试类型…...

jmeter聚合报告中参数详解

sample、average、min、max、90%line、95%line,99%line、Error错误率、吞吐量Thoughput、KB/sec每秒传输的数据量 sample&#xff08;样本数&#xff09; 表示测试中发送的请求数量&#xff0c;即测试执行了多少次请求。 单位&#xff0c;以个或者次数表示。 示例&#xff1a;…...

协议转换利器,profinet转ethercat网关的两大派系,各有千秋

随着工业以太网的发展&#xff0c;其高效、便捷、协议开放、易于冗余等诸多优点&#xff0c;被越来越多的工业现场所采用。西门子SIMATIC S7-1200/1500系列PLC集成有Profinet接口&#xff0c;具有实时性、开放性&#xff0c;使用TCP/IP和IT标准&#xff0c;符合基于工业以太网的…...

Modbus RTU与Modbus TCP详解指南

目录 1. Modbus协议基础 1.1 什么是Modbus? 1.2 Modbus协议历史 1.3 Modbus协议族 1.4 Modbus通信模型 🎭 主从架构 🔄 请求响应模式 2. Modbus RTU详解 2.1 RTU是什么? 2.2 RTU物理层 🔌 连接方式 ⚡ 通信参数 2.3 RTU数据帧格式 📦 帧结构详解 🔍…...

Pydantic + Function Calling的结合

1、Pydantic Pydantic 是一个 Python 库&#xff0c;用于数据验证和设置管理&#xff0c;通过 Python 类型注解强制执行数据类型。它广泛用于 API 开发&#xff08;如 FastAPI&#xff09;、配置管理和数据解析&#xff0c;核心功能包括&#xff1a; 数据验证&#xff1a;通过…...

ThreadLocal 源码

ThreadLocal 源码 此类提供线程局部变量。这些变量不同于它们的普通对应物&#xff0c;因为每个访问一个线程局部变量的线程&#xff08;通过其 get 或 set 方法&#xff09;都有自己独立初始化的变量副本。ThreadLocal 实例通常是类中的私有静态字段&#xff0c;这些类希望将…...

python读取SQLite表个并生成pdf文件

代码用于创建含50列的SQLite数据库并插入500行随机浮点数据&#xff0c;随后读取数据&#xff0c;通过ReportLab生成横向PDF表格&#xff0c;包含格式化&#xff08;两位小数&#xff09;及表头、网格线等美观样式。 # 导入所需库 import sqlite3 # 用于操作…...