为 OpenCV 编写文档(二)

常用命令

这里通过简短的示例描述了最常用的 doxygen 命令。有关可用命令的完整列表和详细说明,请访问命令参考。

基本命令

  • brief - 带有简要实体描述的段落
  • param - 函数参数的描述。

    多个相邻语句合并到一个列表中。如果在实际函数签名中找不到具有此名称的参数 - 将产生 doxygen 警告。函数可以没有记录的参数,也可以记录所有参数。

  • sa - “另请参阅”段落,包含对类、函数、页面或 URL 的引用
  • 注意 - 视觉上突出显示的“注意”段落。多个相邻的语句合并到一个块中。
  • return, returns - 描述函数的返回值
  • overload - 在函数描述中添加固定文本:“这是一个重载成员函数,为方便起见而提供。它与上述函数的区别仅在于它接受的参数。
  • 锚点 - 放置不可见的命名锚点,可以通过命令引用。它只能在页面中使用。ref
  • ref - 对命名部分、页面或锚点的显式引用。

    如果找不到此类实体,将生成 doxygen 警告。此命令有一个可选参数 - 链接文本。

    Doxygen 还会自动生成一些链接:如果文本包含可以在文档实体中找到的单词 - 将生成引用。可以通过在单词前面加上符号来禁用此功能。%

    <span style="background-color:#fbfcfd">Explicit reference: @ref MyClass
    Explicit named reference: @ref example_page "Example page"
    Implicit reference: cv::abc::MyClass1 or just MyClass1
    Disable implicit reference: %MyClass1</span>
  • F - 公式

    内联公式以命令为界:f$

    <span style="background-color:#fbfcfd">\f$ ... \f$</span>

    块公式 - 使用 和 命令:f[f]

    <span style="background-color:#fbfcfd">\f[ ... \f]</span>

代码包含命令

要在文档中将某些文本标记为代码,请使用 code 和 endcode 命令。

<span style="background-color:#fbfcfd"><span style="color:#000000">@code
float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
@endcode
</span></span>

语法将根据当前解析的文件类型突出显示(C++ 表示 .hpp,C 表示 .h),或者您可以在大括号中手动指定它:

<span style="background-color:#fbfcfd"><span style="color:#000000">@code{.xml}
</span></span>

要将整个示例文件包含在文档中,请使用 include 和 includelineno 命令。在常见示例位置搜索该文件,因此您可以仅指定其名称或路径的短部分。includelineno 版本还显示行号,但由于包含行号,因此可以防止复制粘贴。

<span style="background-color:#fbfcfd"><span style="color:#000000">@include samples/cpp/test.cpp
</span></span>

如果要包含现有示例文件的某些部分,请使用 snippet 命令。

首先,用特殊的 doxygen 注释标记文件的所需部分:

<span style="background-color:#fbfcfd"><span style="color:#000000">//! [var_init]
int a = 0;
//! [var_init]
</span></span>

然后将以下代码片段包含在文档中:

<span style="background-color:#fbfcfd"><span style="color:#000000">@snippet samples/cpp/test.cpp var_init
</span></span>

注意

目前,大多数此类部分包含都是使用 dontinclude 命令进行的,以便与旧的 rST 文档兼容。但是,新创建的示例应包含在 snippet 命令中,因为此方法受已处理文件更改的影响较小。

切换按钮包含命令

切换按钮用于显示所选配置(例如编程语言、操作系统、IDE)。

要使用文档中的按钮,请使用 add_toggle 和 end_toggle 命令。

命令add_toggle可以是

  • 常规:add_toggle{按钮名称}
  • 对于C++:add_toggle_cpp
  • 对于 Java:add_toggle_java
  • 对于 Python:add_toggle_python

例:

<span style="background-color:#fbfcfd"><span style="color:#000000">@add_toggle{Button Name}text / code / doxygen commands@end_toggle
</span></span>

例如,使用带有文本和代码片段的切换按钮:

<span style="background-color:#fbfcfd"><span style="color:#000000">### Buttons Example@add_toggle_cppText for C++ button@snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world@end_toggle@add_toggle_javaText for Java button@snippet samples/java/tutorial_code/introduction/documentation/Documentation.java  hello_world@end_toggle@add_toggle_pythonText for Python button@snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world@end_toggle</span></span>

结果如下所示:

按钮示例

C++爪哇岛蟒

“C++ 文本”按钮

std::cout << “Hello World!”;

如您所见,按钮会自动添加到上一个标题下。

分组命令

所有代码实体都应放入表示 OpenCV 模块及其内部结构的命名组中,因此每个模块都应与具有相同名称的组相关联。定义组和子组的好地方是此模块的主头文件:“<module>/include/opencv2/<module>.hpp”。

注意

Doxygen 组称为“模块”,显示在“模块”页面上。

<span style="background-color:#fbfcfd"><span style="color:#000000">/**
@defgroup mymodule My great moduleoptional description
@{@defgroup mymodule_basic Basic operationsoptional description@defgroup mymodule_experimental Experimental operationsoptional description
@}
*/
</span></span>

要将类和函数放入特定组中,只需将 command 添加到其文档中,或者用 command 包装整个代码块:ingroupaddtogroup

<span style="background-color:#fbfcfd"><span style="color:#000000">/** @brief Example function@ingroup mymodule
*/
or
/**
@addtogroup mymodule_experimental
@{
*/
... several functions, classes or enumerations here
/**
@}
*/
</span></span>

出版物参考文献

使用 cite 命令插入对参考书目页面中列出的相关出版物的引用。

首先,将发布 BibTeX 记录添加到“<opencv>/doc/opencv.bib”或“<opencv_contrib>/modules/<module>/doc/<module>.bib”文件中:

<span style="background-color:#fbfcfd"><span style="color:#000000">@ARTICLE{Bradski98,author = {Bradski, Gary R},title = {Computer vision face tracking for use in a perceptual user interface},year = {1998},publisher = {Citeseer}
}
</span></span>

注意

尽量不要添加重复的出版物,因为它可能会在以后混淆文档读者和作者。

然后使用 cite 命令进行引用:

<span style="background-color:#fbfcfd"><span style="color:#000000">@cite Bradski98
</span></span>

注意

要获得出版物的 BibTeX 记录,可以使用 Google Scholar。找到出版物后 - 点击其“引用”链接,然后选择“BibTeX”选项:

scholarship_cite_dialog.png

循序渐进

本节中描述的步骤可以用作文档编写过程中的清单。没有必要以相同的顺序做事,但有些步骤确实取决于前面的步骤。当然,这些步骤只是基本的指导方针,总有创造力的地方。

记录函数

  1. 在函数定义之前添加空的 doxygen 注释。
  2. 在开头添加简短的命令,并简要描述函数含义。
  3. 添加函数的详细说明。
  4. 可选:插入公式、图像和示例代码块以说明复杂案例
  5. 可选:使用 param 命令描述每个参数。
  6. 可选:使用 returns 命令描述函数的返回值。
  7. 可选:添加“另请参阅”部分,其中包含指向类似函数或类的链接
  8. 可选:添加参考书目(如果有)。
  9. 测试代码。(Python:“make check_pylint”)
  10. 生成 doxygen 文档并验证结果。

编写教程

  1. 制定要在本教程中说明的想法。
  2. 使示例应用程序足够简单,以便初学者能够理解。要简明扼要,写描述性注释,不要试图避免所有可能的运行时错误或通用。你的目标是说明这个想法。它应该适合一个源文件!

    如果要将此文件中的代码块插入到教程中,请使用特殊的 doxygen 注释标记它们(请参阅此处)。

    如果要使用多种编程语言编写本教程,请使用切换按钮获取替代注释和代码(请参阅此处)。

  3. 收集申请工作的结果。它可以是“之前/之后”的图像,也可以是代表性能的一些数字,甚至是视频。

    将其保存为适当的格式,以便稍后在本教程中使用:

    • 要保存简单的图形状图像,请使用无损“.png”格式。
    • 对于类似照片的图像 - 有损“.jpg”格式。
    • 数字将以纯文本形式插入,可能格式化为表格。
    • 视频应上传到 YouTube。
  4. 在相应的位置(请参阅此处)创建新的教程页面(“.markdown”-file),并将所有图像文件放在其附近(或“images”子目录中)。还要放置您的示例应用程序文件,并确保在 cmake 步骤上启用选项时,它与 OpenCV 库一起编译。-DBUILD_EXAMPLES=ON
  5. 修改您的新页面:
    • 添加页面标题和标识符,通常以“tutorial_”为前缀(请参阅此处)。您可以使用标识符添加指向上一教程和下一教程的链接
      <span style="background-color:#fbfcfd">@prev_tutorial{identifier}
      @next_tutorial{identifier}</span>

      警告

      不要井号标签 (#),例如: 不正确: 正确:
      <span style="background-color:#fbfcfd">@prev_tutorial{#tutorial_documentation} </span>
      <span style="background-color:#fbfcfd">@prev_tutorial{tutorial_documentation} </span>
    • 添加您的想法和教程目标的简要描述。
    • 描述您的程序和/或其有趣的部分。
    • 描述您的结果,插入以前添加的图像或其他结果。

      要添加 youtube 视频,例如 www.youtube.com/watch?v= ViPN810E0SU,请使用 youtube{Video ID}:

      <span style="background-color:#fbfcfd">@youtube{ViPN810E0SU}</span>
    • 添加参考书目(如果有)(见此处)。
  6. 将新创建的教程添加到相应的目录中。只需找到包含所需表的“table_of_content_*.markdown”文件,并在其中放置类似于现有记录的新记录。

    它只是一个带有特殊子页面命令的列表项,它将页面标记为子页面并将其放入现有页面层次结构中。另请注意列表项缩进、段落之间的空行和特殊的斜体标记。

  7. 生成 doxygen 文档并验证结果。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.hqwc.cn/news/415193.html

如若内容造成侵权/违法违规/事实不符,请联系编程知识网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

亚马逊卖食品有什么具体要求?亚马逊卖食品好做吗?—站斧浏览器

亚马逊卖食品有什么具体要求&#xff1f; 首先&#xff0c;亚马逊要求卖家提供食品的详细信息&#xff0c;包括产品描述、成分表、营养信息和包装规格等。这些信息对于消费者来说至关重要&#xff0c;它们可以帮助消费者了解产品的特点和质量&#xff0c;并做出明智的购买决策…

51单片机原理及应用——张毅刚版本代码全集可复制

从左到右的流水灯的制作(重点) #include <reg51.h> #include <intrins.h> //移位函数的头文件 unsigned int j; void Delay(unsigned int i) // 延时函数 {while(i--) // 注意这里是i--{for(j 0;j < 120;j); // 注意这里是120} }void main() {P1 0xFE;while(1…

INS-06003错误处理

在麒麟V10操作系统上安装Oracle RAC 19C&#xff0c;安装GI的建立互信步骤中&#xff0c;遇到INS-06003错误&#xff1a; [INS-06003] Failed to setup password SSH connectivity with following node(s) 查看详细信息&#xff1a; PRVG-11001: PRCZ-2136: PRCZ-2006: 此时在操…

leetcode82. 删除排序链表中的重复元素 II

文章目录 题目思路1复杂度Code2 思路2复杂度2Code2 题目 给定一个已排序的链表的头 head &#xff0c; 删除原始链表中所有重复数字的节点&#xff0c;只留下不同的数字 。返回 已排序的链表 。 示例 1&#xff1a; 输入&#xff1a;head [1,2,3,3,4,4,5] 输出&#xff1a;…

SpringBoot Redis入门(四)——Redis单机、哨兵、集群模式

单机模式&#xff1a;单台缓存服务器&#xff0c;开发、测试环境下使用&#xff1b;哨兵模式&#xff1a;主-从模式&#xff0c;提高缓存服务器的高可用和安全性。所有缓存的数据在每个节点上都一致。每个节点添加监听器&#xff0c;不断监听节点可用状态&#xff0c;一旦主节点…

CTF CRYPTO 密码学-1

题目名称&#xff1a;enc 题目描述&#xff1a; 压缩包中含两个文件&#xff1a;一个秘钥d.dec&#xff0c;一个密文flag.enc 解题过程&#xff1a; Step1&#xff1a;这题是一个解密他题目&#xff0c;尝试openssl去ras解密 工具简介 在Kali Linux系统中&#xff0c;openss…

深入理解 Kubernetes Ingress:路由流量、负载均衡和安全性配置

Kubernetes Ingress 是 Kubernetes 集群中外部流量管理的重要组件。它为用户提供了一种直观而强大的方式&#xff0c;通过定义规则和配置&#xff0c;来控制外部流量的路由和访问。 1. 什么是 Ingress&#xff1f; 在 Kubernetes 中&#xff0c;Ingress 是一种 API 资源&#…

C语言--质数算法和最大公约数算法

文章目录 1.在C语言中&#xff0c;判断质数的常见算法有以下几种&#xff1a;1.1.试除法&#xff08;暴力算法&#xff09;&#xff1a;1.2.优化试除法&#xff1a;1.3.埃拉托色尼筛法&#xff1a;1.4.米勒-拉宾素性检验&#xff1a;1.5.线性筛法&#xff1a;1.6.费马小定理&am…

LLM:Scaling Laws for Neural Language Models (中)

核心结论 1&#xff1a;LLM模型的性能主要与计算量C&#xff0c;模型参数量N和数据大小D三者相关&#xff0c;而与模型的具体结构 (层数/深度/宽度) 基本无关。三者满足: C ≈ 6ND 2. 为了提升模型性能&#xff0c;模型参数量N和数据大小D需要同步放大&#xff0c;但模型和数…

赋能客户不停歇,卓翼飞思职业院校无人智能装备师资培训圆满落幕

1月10日-15日&#xff0c;卓翼飞思在北京研发中心成功举办职业院校无人智能装备高级师资培训。来自湖南汽车工程职业学院&#xff08;以下简称&#xff1a;湖南汽车职院&#xff09;的10名师生&技术人员参与此次培训&#xff0c;针对无人智能集群应用开发进行系统性的培训及…

重生奇迹MU快速升级

1、前期&#xff0c;都是主线任务&#xff0c;我们必须要跟着主线任务走&#xff0c;前面的话升级一次需要的经验很少的&#xff0c;一天下来可以升级100级是轻轻松松的&#xff0c;主线任务是比较多的&#xff0c;我们跟着任务一直做差不多可以到150级&#xff0c;接下来就是后…

flink学习之水位线

什么是水位线 在事件时间语义下&#xff0c;我们不依赖系统时间&#xff0c;而是基于数据自带的时间戳去定义了一个时钟&#xff0c; 用来表示当前时间的进展。于是每个并行子任务都会有一个自己的逻辑时钟&#xff0c;它的前进是靠数 据的时间戳来驱动的。 我们可以把时钟也以…