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

最新推荐文章于 2024-06-25 22:00:00 发布
最新推荐文章于 2024-06-25 22:00:00 发布
阅读量2.7k 收藏 5
点赞数 2
分类专栏： c/c++ 文章标签： c语言 编程规范 doxygen
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/MULTISENSOR/article/details/41347679
版权
本文档详细介绍了如何使用Doxygen为C语言程序编写规范的注释，以便自动生成高质量的文档。Doxygen是一个强大的文档生成工具，支持多种编程语言，并能输出HTML、XML等多种格式。主要内容包括：Doxygen的基本概念、注释格式规范、文件头注释、版权信息、模块和分组定义、变量、宏和函数的注释说明，以及如何使用DoxyWizard生成CHM文档。
摘要由CSDN通过智能技术生成

目录

1、什么是Doxygen?. 3

2、撰写正确格式的批注... 4

2.1常用指令介绍... 4

2.2简述与详述的方式... 6

2.3文件头注释... 6

2.4版权注释... 6

2.5模块定义（单独显示一页）... 7

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

最低0.47元/天 解锁文章
MULTISENSOR
关注
专栏目录
c语言注释含义,C语言编程规范——注释
weixin_40009393的博客
05-19 1661
前言制定C语言的编程规范，对代码的清晰、简洁、可测试、安全、程序效率、可移植各个方面有巨大的作用。良好的注释能让整个代码读起来更加流畅，此乃程序猿出差旅行，通宵熬夜必备良药......注释的原则注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。 示例：如下注释意义不大。/* if receive_flag is TRUE */if (re...
C语言注释
WhaleM的博客
01-11 1103
C语言注释 源代码 #include <stdio.h> int main() { int i,j; scanf("%d",&i); if(i<30) j=1; else if(i>60) j=2; else j=0; printf("j=%d\n",j); } 代码内部用“//”注释，外部用“...
前端：HTML、CSS、JavaScript 代码注释 / 注释与代码规范
最新发布
snowball的博客
06-25 4403
HTML注释是在HTML代码中添加说明和解释的一种方法，这些注释不会被浏览器渲染或显示在页面上，而是被浏览器忽略。使用单行注释或多行注释：对于较短的注释，可以使用单行注释；对于较长的注释或需要跨越多行的注释，应使用多行注释。使用有意义的注释：确保注释提供了有价值的信息，而不是简单的“TODO”或“此处需要修改”。结束来标记多行注释。位于被注释的代码附近：通常，注释应位于被注释的代码之前或之上，以便于阅读和理解。位于被注释的代码之前：通常，注释应位于被注释的代码之前，以便于阅读和理解。
C语言程序注释风格
有理论，有实验，有结论，可为一篇文章
08-17 990
良好编程习惯的养成对于一个程序员的发展非常重要，而注释对于一份程序来讲又是一个必不可少的组成部分，今天来研究一下C语言程序的注释风格。 注释是源码程序中非常重要的一部分，一般情况下，源程序有效注释量必须在15%以上。 注释的原则是有助于对程序的阅读理解，所以注释语言必须准确、易懂、简洁，注释不宜太多也不能太少，注释的内容要清楚、明了、含义准确，防止注释二义性，该加的地方一定要加，但不必要的地方一定...
c语言输入注释,注释C语言代码
weixin_39641257的博客
05-22 107
满意答案6478qucz2013.05.30采纳率：44%等级：12已帮助：4734人#include"stdio.h"#include"string.h"// LFSR进动一拍unsigned char *LFSR_go(unsigned char *pzt, unsigned char *pjg, int n) //n为状态区字节数{unsigned char t=0;int c=0,...
C之代码注释
Eureka1024的博客
10-25 1531
C语言中，因为某些原因（比如调试），我们经常需要把一段代码注释掉，许多初学者一般使用/*  */来注释你想暂时不需要，可能以后需要的代码，即 /*  你想注释掉的代码*/ 这种做法存在一些可怕的风险，因为在C语言中，注释不允许嵌套，第一个/* 会与第一个*/结合，也就是说如果你注释的代码里面本身就存在用/* */注释，那么你注释这段代码时将会出错，举个例子： /*    int i;   /
编程 | C/C++代码规范注释
C语言C++学习俱乐部：765860056
04-22 625
注释风格 1. 总述 一般使用//或/**/，只要统一就好。 2. 说明 //或/**/都可以，但团队要在如何注释及注释风格上确保统一。 文件注释 1. 总述 在每一个文件开头加入版权、作者、时间等描述。 文件注释描述了该文件的内容，如果一个文件只声明，或实现，或测试了一个对象，并且这个对象已经在它的声明处进行了详细的注释，那么就没必要再加上文件注释，除此之外的其他文件都需要文件注释。 2. 说明 法律公告和作者信息： 每个文件都应该包含许可证引用。也要为项目选择合适的许可证版..
华为技术有限公司c语言编程规范-pdf
09-12
《华为技术有限公司C语言编程规范》是一份详细指导程序员遵循的最佳实践文档，旨在提高代码质量、可读性以及可维护性。这份规范不仅对华为公司内部的开发人员有着重要的指导意义，同时也为广大的C语言开发者提供了...
华为C语言编程规范-综合文档
05-23
《华为C语言编程规范》是一份综合性的指导文档，旨在为C语言的开发人员提供一套标准和最佳实践，以确保代码的质量、可读性、可维护性和安全性。这份规范不仅适用于华为公司内部的开发团队，同时也对广大C语言开发者...
C 语言注释
wuxiaopengnihao1的博客
05-28 1022
C 语言：注释 本文章通过语法和示例说明了如何在 C 语言中使用注释。更多C教程请访问码农之家 描述 在 C 编程语言中，您可以在源代码中放置不作为程序一部分执行的注释。 注释使 C 源代码更清晰，使其他人能够更好地理解代码的目的，并极大地帮助调试代码。注释在包含数百或数千行源代码的大型项目中或在许多贡献者正在处理源代码的项目中尤其重要。 注释以斜杠星号开头，以星/*号斜杠结尾，*/可以在程序中的任何位置。注释可以跨越 C 程序中的多行。注释通常直接添加在相关 C 源代码的上方。 强烈...
c语言贪吃蛇源码（带注释）
06-24
用windows api 做的贪吃蛇 #include #include"resource.h" #include"Node.h" #include #include TCHAR szAppname[] = TEXT("Snack_eat"); #define SIDE (x_Client/80) #define x_Client 800 #define y_Client 800 #define X_MAX 800-20-SIDE //点x的范围 #define Y_MAX 800-60-SIDE //点y的范围 #define TIME_ID 1 #define SECOND 100 #define NUM_POINT 10 //点的总个数 #define ADD_SCORE 10 LRESULT CALLBACK WndProc(HWND, UINT, WPARAM, LPARAM); int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, PSTR szCmdLine, int iCmdShow) { HWND hwnd; //窗口句柄 MSG msg; //消息 WNDCLASS wndclass; //窗口类 HACCEL hAccel;//加速键句柄 wndclass.style = CS_HREDRAW | CS_VREDRAW; //窗口的水平和垂直尺寸被改变时，窗口被重绘 wndclass.lpfnWndProc = WndProc; //窗口过程为WndProc函数 wndclass.cbClsExtra = 0; //预留额外空间 wndclass.cbWndExtra = 0; //预留额外空间 wndclass.hInstance = hInstance; //应用程序的实例句柄，WinMain的第一个参数 wndclass.hIcon = LoadIcon(NULL, IDI_APPLICATION); //设置图标 wndclass.hCursor = LoadCursor(NULL, IDC_ARROW); //载入预定义的鼠标指针 wndclass.hbrBackground = (HBRUSH)GetStockObject(WHITE_BRUSH); //设置画刷 wndclass.lpszMenuName = szAppname; //设置菜单 wndclass.lpszClassName = szAppname; //设置窗口类的名字 if (!RegisterClass(&wndclass))//注册窗口类 { MessageBox(NULL, TEXT("这个程序需要windows NT!"), szAppname, MB_ICONERROR); return 0; } hwnd = CreateWindow(szAppname, TEXT("Snack_eat"),//CreateWindow函数调用时，WndProc将受到WM_CREATE WS_OVERLAPPEDWINDOW&~WS_THICKFRAME& ~WS_MAXIMIZEBOX,//普通的层叠窗口&禁止改变大小&禁止最大化 CW_USEDEFAULT, //初始x坐标（默认） CW_USEDEFAULT, //初始y坐标 x_Client, //初始x方向尺寸 770 y_Client, //初始y方向尺寸 750 NULL, //父窗口句柄 NULL, //窗口菜单句柄 hInstance, //程序实例句柄 WinMain函数中第二个参数 NULL); //创建参数 ShowWindow(hwnd, iCmdShow);//显示窗口，iCmdShow是WinMain的第四个参数，决定窗口在屏幕中的初始化显示形式，例：SW_SHOWNORMAL表示正常显示 UpdateWindow(hwnd);//使窗口客户区重绘，通过向WndProc发送一条WM_PAINT消息而完成的 hAccel = LoadAccelerators(hInstance, szAppname);//加载加速键 while (GetMessage(&msg, NULL, 0, 0)) { if (!TranslateAccelerator(hwnd, hAccel, &msg)) { TranslateMessage(&msg); DispatchMessage(&msg); } }/* while (GetMessage(&msg, NULL, 0, 0))//GetMessage函数从消息队列中得到消息，填充msg。如果msg.message等于WM_QUIT，返回0，否则返回非0 { TranslateMessage(&msg);//将msg返回给windows已进行某些键盘消息的转换 DispatchMessage(&msg);//将msg再次返回给windows }*/ return msg.wParam;//msg.wParam是PostQuitMessage函数的参数值，通常是0 } ...
C语言经典源代码220例带注释讲解【重点推荐】
12-25
C语言经典源代码220例。绝对经典的源代码，由浅入深，每个实例都带有注释和讲解，是C语言入门和提高的难得好教材，还有大多数基本算法的实现例子，无论学习还是工作都十分有用。覆盖了C语言学习的所有知识点。内有目录。已经压缩成zip格式。重点推荐。
C语言代码注释 - C语言零基础入门教程
baidu_1234567的博客
12-30 585
C语言代码注释 - C语言零基础入门教程
c语言注释规范
fengyunjh6的专栏
01-05 475
http://wenku.baidu.com/view/b082631eff00bed5b9f31d58.html http://wenku.baidu.com/view/a56c8975a26925c52cc5bfd9.html
大写C语言注释
人生如梦
01-07 2802
昨天无意中看到一道题：“编写一个程序，使一段合理C语言中的注释全部大写“。突然兴趣来了，于是决定自己动手来试试。这道题目看起来很简单，但是实际动起手来，还是有点难度。 C语言注释说明 注意问题 状态变化图 状态定义 状态变迁 完整代码C语言注释说明C语言的注释分为两种，一种是单行注释，一种是多行注释。 单行注释：顾名思义就是当遇到换行之后即表示注释已结束，用//表示 多行注释：注释以/*开始并且以*
c语言-注释
weixin_30273501的博客
02-26 123
“注释”是字符序列由编译器将一个空白字符和否则将忽略的一个正斜杠/星号组合 (/*) 开头。注释可以包括任何字符组合可以从可用的字符集的，包括换行符，但是，排除 “结束注释”分隔符 (*)。注释占用多个行，但不能嵌套。 注释可以显示任何位置空白字符授权。因为编译器将注释作为一个空白字符，不能包括在标记中的注释。编译器忽略在注释的字符。 使用文档注释代码。此示例是编译器接受的...
C语言中的注释方法
weixin_40316053的博客
10-15 3596
C语言中的注释方法
C语言编程规范 - 嵌入式软件开发指南
"C语言编程规范" 这篇文档是作者基于华为的嵌入式C语言实践、MISRA-C-2004标准以及ISO/IEC 9899:1990（C语言标准）等资料，结合自身经验制定的一套C语言编程规范，特别针对嵌入式系统开发。其目标是提升代码质量，...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值