Doxygen注释与自定义模板对比：对文档生成及可读性的影响

我正在遵循C编码规范养成编程习惯，以提升代码一致性。了解到Doxygen广泛用于软件项目文档自动生成，但对其使用并不熟悉。我当前使用自定义的文件头和函数注释模板，而非Doxygen标准的带@命令的模板，想请教三个问题：

1. 这种自定义注释模板会影响Doxygen的使用吗？
2. 会对其他开发者的代码可读性造成影响？
3. 还是仅作为注释无不良影响？

我的自定义文件头注释模板：

/* =================================================================================================================
  FILE DESCRIPTION
  ------------------------------------------------------------------------------------------------------------------
  File        : dio.c
  Category    : drivers - dio
  Date        : 25 Jan. 2023
  Author      : Nabil Yasser
  Git Account : 
  Description : Includes DIO driver functions Implementation for ATmega32
==================================================================================================================== */

对比Doxygen标准文件头模板：

/**
 * @file dio.c
 * @author Nabil Yasser
 * @brief 
 * @version 0.1
 * @date 31/01/2023
 * 
 * @copyright Copyright (c) 2023
 * 
 */

我的自定义函数注释模板：

/* =================================================================================================================
 * Syntax      : uint8 dio_setPin(DioPortId_et portId, DioChannelId_et channelId, DioChannelDirection_et direction)
 * Description : Sets DIO pins direction as output or input
 * Sync/Async  : Synchronous
 * Reentrancy  : Non Reentrant
 * Arguments   : portId    : Port name in which the pin you want to set direction for (GPIOA, GPIOB, GPIOC, GPIOD).
 *             : channelId : Name of channel/pin you want to set direction for (PIN0 ~ PIN7)
 *             : direction : Channel/pin direction (INPUT, OUTPUT)
 * Output      : E_OK (0)  : If no problems
 *             : E_NOK (1) : If there is any problem
==================================================================================================================== */

对比Doxygen标准函数注释模板：

/**
 * @brief function desciption text
 * 
 * @param portId description about parameter
 * @param channelId description about parameter
 * @param direction description about parameter
 * @return uint8 description about return value
 */

问题解答 #

1. 对Doxygen使用的影响 #

默认情况下，Doxygen不会解析你的自定义注释模板：

• Doxygen识别的文档注释块是/** ... */（开头多一个星号），而你的模板是/* ... */，属于普通注释，不会被当作文档注释处理。
• 你模板里的File、Syntax、Sync/Async等字段不是Doxygen的标准命令，即使把注释块改成/** ... */，这些内容也不会被Doxygen识别并提取到生成的文档中。

如果想让Doxygen兼容你的模板，有两种方案：

• 调整自定义模板，将字段替换为Doxygen支持的格式，比如把Syntax改成@par Syntax:，Sync/Async改成@par Sync/Async:，既保留原有信息，又能被Doxygen解析。
• 在Doxygen配置文件中添加自定义别名，例如：

  ALIASES += "Syntax=\par Syntax:"
  ALIASES += "SyncAsync=\par Sync/Async:"
  ALIASES += "Reentrancy=\par Reentrancy:"
  

  这样Doxygen就能识别你自定义的字段，并将其纳入生成的文档。

2. 对其他开发者可读性的影响 #

这取决于项目的协作场景：

• 如果是内部团队项目，只要所有人统一遵循这个自定义模板，且模板结构清晰（比如你加入了Sync/Async、Reentrancy这类Doxygen默认模板没有的关键信息），反而能提升可读性，因为团队成员都熟悉规则。
• 如果是开源项目或跨团队合作，其他开发者可能更习惯Doxygen的标准格式，需要额外学习你的自定义模板规则，会有一定的理解门槛。

3. 仅作为注释的影响 #

完全没有不良影响。无论用哪种注释格式，编译器都会忽略所有注释内容，不会影响代码的编译和运行。只要注释内容清晰、结构一致，本质上都是给开发者看的辅助信息。

内容的提问来源于stack exchange，提问作者Nabil Yasser