C语言编程规范--代码注释

最新推荐文章于 2025-06-09 12:12:38 发布

MULTISENSOR

最新推荐文章于 2025-06-09 12:12:38 发布

阅读量2.8k

点赞数 2

CC 4.0 BY-SA版权

分类专栏： c/c++ 文章标签： c语言编程规范 doxygen

本文链接：https://blog.youkuaiyun.com/MULTISENSOR/article/details/41347679

本文档详细介绍了如何使用Doxygen为C语言程序编写规范的注释，以便自动生成高质量的文档。Doxygen是一个强大的文档生成工具，支持多种编程语言，并能输出HTML、XML等多种格式。主要内容包括：Doxygen的基本概念、注释格式规范、文件头注释、版权信息、模块和分组定义、变量、宏和函数的注释说明，以及如何使用DoxyWizard生成CHM文档。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

2.6分组定义（在一页内分组显示）... 8

2.7变量、宏定义、类型定义简要说明... 8

2.8函数说明... 9

2.9枚举类型定义... 9

2.10项目符号标记... 10

3、使用DoxyWizard生成CHM文档... 11

1、什么是Doxygen?

Doxygen是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。

Doxygen就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。

因此，Doxygen的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。

目前Doxygen可处理的程序语言包含：

C/C++
Java
IDL (Corba, Microsoft及KDE-DCOP类型)

而可产生出来的文档格式有：

HTML
XML
LaTeX
RTF
Unix Man Page

而其中还可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透过一些工具产生出PS或是PDF文档。

2、撰写正确格式的批注

若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：
    1）文件头（包括.h和.cpp）
        主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
    2）类的定义
        主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
    3）类的成员变量定义
        在类的成员变量上方，对该成员变量进行简要地描述
    4）类的成员函数定义
        在类定义的成员函数上方，对该成员函数功能进行简要描述
    5）函数的实现在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

2.1常用指令介绍

可以在注释中加一些Doxygen支持的指令，主要作用是控制输出文档的排版格式，使用这些指令时需要在前面加上“\”或者“@”（JavaDoc风格）符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档，下面对比较常用的指令做一下简单介绍。

@file	档案的批注说明。 eg： @file stm32f10x_tim.c
@author	作者的信息 eg： @author MCD Application Team
@brief	用于class或function的批注中，后面为class或function的简易说明。 eg： @brief This file provides all the TIM firmware functions.
@param	主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明 eg： @param TIMx: where x can be 1, 2, 3, 4, 5 or 8 to select the TIM peripheral.
@return	描述该函数的返回值情况 eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval	描述返回值类型，主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。 eg: @retval NULL 空字符串。 @retval !NULL 非空字符串。
@note	注解
@attention	注意
@warning	警告信息
@enum	引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg： @enum CTest::MyEnum
@var	引用了某个变量，Doxygen会在该枚举处产生一个链接 eg： @var CTest::m_FileKey
@class	引用某个类，格式：@class <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h"
@exception	可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常
@todo	对将要做的事情进行注释