正文

Doxygen -- 多个函数的单个注释块

 2023-02-21  11

关键词：

【中文标题】Doxygen -- 多个函数的单个注释块【英文标题】：Doxygen -- Single Comment Block for Multiple Functions 【发布时间】：2016-09-14 01:00:43 【问题描述】：

你能用一个注释块来注释 doxygen 中的多个函数吗？下面是一个不起作用的简单示例。我可以做类似的事情来得到我想要的吗？

文件.cpp

#include file.h

/// @name FunsGroupedInDoxygen
///@
/**
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
int fun1(int aParam) return 0;
int fun2(int aParam) return 0;
///@

文件.h

int fun1(int aParam);
int fun2(int aParam);

氧气输出：

警告：文件 file.h 的成员 fun2(int aParam)（函数）未记录。

【问题讨论】：

我很难想出一个理由来解释为什么你不单独做。为什么要为两个函数使用相同的文档？如果它们的差异不足以保证不同的描述，那么为什么它们是两个独立的功能？ @Tuffwer 够公平的。让我给你一个具体的例子。在我使用的一些库中，有一些函数可以控制特定的硬件引脚。这些函数只能在目标输出上有所不同。在模拟这些函数时，我想将它们组合在一起，它们的文档几乎是相同的。也许您希望每个文档行都不同。嗯，这是有道理的，如果输出需要不同，因为它使用硬件而不是完全在软件中工作。在那种情况下，我会拍摄更多的混合体，并尝试用一个块来描述函数系列，但作为最终用户，我仍然认为我需要至少一行来解释特定函数的特定输出目标是什么曾是。感谢您解释您的情况，我从未处理过在硬件级别交互的代码（对于类似问题要记住的一个很好的用例），也许是时候拿起树莓派了。 @Tuffwer 我确实喜欢你的方法。到目前为止，当我尝试这样做时，基本上都没有成功。 【参考方案1】：

我不确定是否有单个评论块，但一种简洁明了的方法是使用 @copydoc (reference here)，例如：

/**
 * @brief Brief description
 * @param aParam A parameter
 */
void foo(int aParam) 

/**
 * @copydoc foo(int)
 */
void bar(int aParam)

【讨论】：

【参考方案2】：

查看Doxygen manual 中的分组，这里有几种方法可以使用。我认为最适合这种情况的一种称为成员组。

您可以使用以下两种样式之一定义成员组：

///@ 
  ...
///@

或

/**@*/ 
  ... 
/**@*/

这方面的一个例子是：

/** @name FunctionGroup
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
///@
//* fun1 specific description */
int fun1(int aParam) return 0;
//* fun2 specific description */
int fun2(int aParam) return 0;
///@

这允许您定义一个可以为其提供通用描述的组，并且仍然允许您在创建的 doxygen 文件中删除特定于每个函数的注释。

我没有在我所在的计算机上安装 doxygen，因此无法直接测试此代码，但是如果遵循文档中成员组部分的 group2 中的示例，则该示例的编译输出为 @ 987654322@，希望这是您想要的输出。

编辑：

经过测试，前一个确实对我有用，但只有当我将所需的提取模式设置为所有实体（doxyfile 中的 EXTRACT_ALL = YES）时。最好只使用实际记录的实体，因此我花了一些时间尝试与上述文档不同的方法。

文件.h：

/**
 * \defgroup FunctionGroup A Group of Functions
 * @brief Documentation for 2 functions
 * @param aParam A Parameter
 * @retval 0 will always be returned
 * @
 */ 
int fun1(int aParam);
int fun2(int aParam);
 /** @ */

文件.cpp：

#include file.h

/** @ingroup FunctionGroup
 * @brief fun1 specific description
 */
 int fun1(int aParam)
    return 0;
 
/** @ingroup FunctionGroup
 * @brief fun2 specific description
 */
 int fun2(int aParam)
    return 0;

这是我在这两个文件上运行 Doxygen 时得到的输出图像：

我在 Windows 机器上使用了 doxywizard，我由此生成的 doxyfile 是 on pastebin。

【讨论】：

Doxygen 告诉我：temp/file.h:18：警告：文件 file.h 的成员 fun1(int aParam)（函数）未记录。 temp/file.h:19：警告：文件 file.h 的成员 fun2(int aParam)（函数）未记录。据我所知，所有示例都处理类内部的成员函数，而不是独立函数。稍后我会在我的机器上安装 Doxygen 并查看是否可以敲出一些东西。 @Napthali 好的，我添加了另一种似乎可以使用本质上应该是默认 Doxygen 配置的方法。让我知道这是否适合您我还设置了 set DISTRIBUTE_GROUP_DOC 到 YES。【参考方案3】：

DISTRIBUTE_GROUP_DOC 选项具有您想要的效果。全局启用相对无害，因为即使设置了HIDE_UNDOC_MEMBERS，成员组中未记录的成员也会（仅）出现在页面的摘要表中。

请注意，“成员子组”适用于 \defgroup 组以及类和命名空间。

【讨论】：

doxygen注释语法规范(代码片段)

...样的规范作为自己的编程注释习惯，提高自己的软实力。Doxygen注释语法注释格式块注释建议统一使用/**……***/行注释建议统一使用///<…/**……*/Doxygen常用注释命令@exception<exception-object>exceptiondescription对一个异常对象进行... 查看详情

Terraform：如何在单个资源块中提供多个 lambda 函数 zip 文件

】Terraform：如何在单个资源块中提供多个lambda函数zip文件【英文标题】：Terraform:howtoprovidemultiplelambdafucntionzipfilesinasingleresourceblock【发布时间】：2021-12-0914:09:03【问题描述】：为1个lambda函数工作的sn-p。Terraform版本0.14.9。resource"aw... 查看详情

在对 GPU 内核进行 doxygen 注释时，如何记录有关网格的信息？

】在对GPU内核进行doxygen注释时，如何记录有关网格的信息？【英文标题】：Whendoxygen-commentingaGPUkernel,howdoIdocumentinformationaboutthegrid?【发布时间】：2020-08-1901:46:46【问题描述】：在为函数编写doxygen注释时，我使用@param作为它的参... 查看详情

用doxygen风格注释代码生成文档(代码片段)

目录用doxygen风格注释代码生成文档1.说明2.具体操作2.1生成头部注释2.2安装doxygen2.3工程配置3.总结用doxygen风格注释代码生成文档1.说明目前由代码生成文档的方式将使项目变得简单，同时生成的文档也会将与代码同步起来。要注... 查看详情

doxygen+graphviz轻松绘制函数调用图（callgraph）

...没有购买，因此需要寻找一个免费、跨平台的替代工具。doxygen+graphviz是不错的选择。原文参考：https://blog.csdn.net/benkaoya/article/details/797636681介绍doxygen是跨平台的工具，官网：http://www.doxygen.nl/支持Linux、Windows、MacOSX系统（本文将... 查看详情

// doxygen 中的注释

】//doxygen中的注释【英文标题】：//commentsindoxygen【发布时间】：2012-02-2822:02:42【问题描述】：我有一个需要用doxygen记录的c#项目。它会拾取由VisualStudio的///自动生成的cmets，但不幸的是它不会拾取正常的//cmets。是否有我缺少的... 查看详情

代码注释规范之doxygen

一Doxygen简介Doxygen是一个程序的文档产生工具，可以将程序中的注释转换成说明文档或者说是API参考手册，从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写，才能让Doxygen识别和转化。... 查看详情

记录文件、类和构造函数的正确方法是啥？

】记录文件、类和构造函数的正确方法是啥？【英文标题】：Whatistheproperwaytodocumentfiles,classesandconstructors?记录文件、类和构造函数的正确方法是什么？【发布时间】：2011-08-1003:52:58【问题描述】：为构造函数和类以及仅包含单个... 查看详情

将多个内存块呈现为单个连续块的容器

】将多个内存块呈现为单个连续块的容器【英文标题】：Containertopresentmultiplememorychunksassinglecontinuousone【发布时间】：2012-03-1908:10:22【问题描述】：是否有一些“标准”容器（STL、boost）可以将多个内存块呈现为单个连续的块？... 查看详情

doxygen教程之注释风格(代码片段)

...为什么大多数人学不会人工智能编程？>>> doxygen是一个开源的C++接口文档生成工具。要使用doxygen生成接口文档，就必须遵循它的注释规范，下面对它的注释规范进行简单介绍。1.JavaDoc风格注释：/**... 查看详情

代码注释规范之doxygen

doxygen教程之注释风格(代码片段)

使用注释将单个实体映射到休眠中相同模式的多个表

】使用注释将单个实体映射到休眠中相同模式的多个表【英文标题】：Mappingasingleentitytomultipletablesofsameschemainhibernateusingannotations【发布时间】：2016-03-2912:54:21【问题描述】：我有一个类CustomerProfile，它映射到表CUST_PROFILE。我们需... 查看详情

如何从 Android 中的多个声音块创建单个声音文件

】如何从Android中的多个声音块创建单个声音文件【英文标题】：HowtocreatesinglesoundfilefrommultiplechunksofsoundsinAndroid【发布时间】：2015-08-1013:29:40【问题描述】：我正在创建一个鼓应用程序，我必须在其中做两件事播放各种声音如果... 查看详情

常见文档注释工具简介

DoxygenDoxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxygen可以从一套归档源文件开始，生成HTML格式的在线类浏览... 查看详情

doxygen生成美丽注释文档：初体验(代码片段)

HelloDoxygen[TOC]Chapter1-准备工作(Windows环境)1.1程序包下载Doxygen源码：gitclonehttps://github.com/doxygen/doxygen.gitGUI版本：点击下载便携压缩包版本：下载32位版本64位版本HTMLHelpWorkshop用于生成CHM文件，便于传播和查看。Htmlhelp.exeGraphviz用于... 查看详情

代码说明书生成神器—doxygen

Doxygen是一个程序的文档产生工具，可以将程序中的注释转换成说明文档或者说是API参考手册，从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写，才能让Doxygen识别和转化。目前Doxygen可... 查看详情

doxygen的使用配置并生成文档

原创文章，欢迎阅读，禁止转载。doxygen是个好用的文档生成工具，他的强大功能有很多介绍，我就不说了。自带的chm帮助手册很全面，包括功能、注释规范、怎么配置、工具用法等。doxygen的用法共3步:1.按照注释规范对代码加注... 查看详情