基于Doxygen的C C++注释原则_@see doxygen

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，涵盖了95%以上物联网嵌入式知识点，真正体系化！

由于文件比较多，这里只是将部分目录截图出来，全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、电子书籍、讲解视频，并且后续会持续更新

需要这些体系化资料的朋友，可以加我V获取：vip1024c （备注嵌入式）

如果你需要这些资料，可以戳这里获取

3. 类、结构、枚举标注

4. 函数注释原则

5. 变量注释

6. 模块标注

7. 分组标注

总述

华丽的分隔线

//---------------------------------------------------------------------------

// Platform Defines

//---------------------------------------------------------------------------

enum

{

OST_PLATFORM_WIN32 = 1,

OST_PLATFORM_LINUX_X86 = 2,

OST_PLATFORM_LINUX_ARM = 3,

OST_PLATFORM_ANDROID = 4,

OST_PLATFORM_MACOSX = 5,

};

//---------------------------------------------------------------------------

// API Export/Import Macros

//---------------------------------------------------------------------------

/** Indicates an exported and imported shared library function. */

#define OST_API_EXPORT __declspec(dllexport)

#define OST_API_IMPORT __declspec(dllimport)

//---------------------------------------------------------------------------

// Digital Image Macros

//---------------------------------------------------------------------------

#define OST_PI 3.141592653589793f

#define OST_RGB2GRAY(r, g, b) ( ((b) * 117 + (g) * 601 + ® * 306) >> 10 )

//---------------------------------------------------------------------------

// date and time at compile time

//---------------------------------------------------------------------------

#define OST_TIMESTAMP DATE " " TIME

1. 文件头的标注

/*****************************************************************************

* OpenST Basic tool library *

* Copyright © 2014 Henry.Wen renhuabest@163.com. *

* *

* This file is part of OST. *

* *

* This program is free software; you can redistribute it and/or modify *

* it under the terms of the GNU General Public License version 3 as *

* published by the Free Software Foundation. *

* *

* You should have received a copy of the GNU General Public License *

* along with OST. If not, see http://www.gnu.org/licenses/. *

* *

* Unless required by applicable law or agreed to in writing, software *

* distributed under the License is distributed on an “AS IS” BASIS, *

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *

* See the License for the specific language governing permissions and *

* limitations under the License. *

* *

* @file Example.h *

* @brief 对文件的简述 *

* Details. *

* *

* @author Henry.Wen *

* @email renhuabest@163.com *

* @version 1.0.0.1(版本号) *

* @date renhuabest@163.com *

* @license GNU General Public License (GPL) *

* *

*----------------------------------------------------------------------------*

* Remark : Description *

*----------------------------------------------------------------------------*

* Change History : *

* | | | *

*----------------------------------------------------------------------------*

* 2014/01/24 | 1.0.0.1 | Henry.Wen | Create file *

*----------------------------------------------------------------------------*

* *

*****************************************************************************/

2.命名空间

/**

* @brief 命名空间的简单概述 \n(换行)

* 命名空间的详细概述

*/

namespace OST

{

}

3. 类、结构、枚举标注

/**

* @brief 类的简单概述 \n(换行)

* 类的详细概述

*/

class Example

{

};

枚举类型定义、结构体类型定义注释风格类似

/**

* @brief 简要说明文字

*/

typedef struct 结构体名字

{

成员1, /*!< 简要说明文字 */ or ///<说明， /**<说明 */ 如果不加<，则会认为是成员2的注释

成员2, /*!< 简要说明文字 */ or ///<说明， /**<说明 */

成员3, /*!< 简要说明文字 */ or ///<说明， /**<说明 */

}结构体别名；

4. 函数注释原则

/**

* @brief 函数简要说明-测试函数

* @param index 参数1

* @param t 参数2 @see CTest

*

* @return 返回说明

* -false fail

* -true succeed

*/

bool Test(int index, const CTest& t);

note：指定函数注意项事或重要的注解指令操作符

note格式如下：

@note 简要说明

retval：指定函数返回值说明指令操作符。(注:更前面的return有点不同.这里是返回值说明)

retval格式如下：

@retval 返回值 简要说明

pre：指定函数前置条件指令操作符

pre格式如下：

@pre 简要说明

par：指定扩展性说明指令操作符讲。（它一般跟code、endcode一起使用 ）

par格式如下：

@par 扩展名字

code、endcode：指定

code、endcode格式如下：

@code

简要说明(内容)

@endcode

see：指定参考信息。

see格式如下：

@see 简要参考内容

deprecated：指定函数过时指令操作符。

deprecated格式如下：

@deprecated 简要说明

　　　　调试Bug说明  
 　　　　　　解决的bug说明，@bug  
　　　　警告说明 (warning)  
　　　　　　定义一些关于这个函数必须知道的事情，@warning  
　　　　备注说明 (remarks)  
　　　　　　定义一些关于这个函数的备注信息，@remarks  
　　　　将要完成的工作 (todo)  
　　　　　　说明哪些事情将在不久以后完成，@todo  
　　　　使用例子说明 (example)  
 　　　　　　例子说明，@example example.cpp

*/**

* @brief 打开文件 \n

* 文件打开成功后，必须使用::CloseFile函数关闭

* @param[in] fileName 文件名

* @param[in] fileMode 文件模式，可以由以下几个模块组合而成：

* -r读取

* -w 可写

* -a 添加

* -t 文本模式(不能与b联用)

* -b 二进制模式(不能与t联用)

* @return 返回文件编号

* --1表示打开文件失败(生成时:.-1)

* @note文件打开成功后，必须使用::CloseFile函数关闭

* @par 示例:

* @code

* //用文本只读方式打开文件

* int ret = OpenFile(“test.txt”, “a”);

* @endcode

* @see 函数::ReadFile::CloseFile (“::”是指定有连接功能,可以看文档里的CloseFile变成绿,点击它可以跳转到CloseFile.)

* @deprecated由于特殊的原因，这个函数可能会在将来的版本中取消

*/

int OpenFile(const char* fileName, const char* fileMode);

/**

* @brief 关闭文件

* @param [in] file 文件

*

* @retval 0 成功

* @retval -1 失败

* @pre file 必须使用OpenFile的返回值

*/

int CloseFile(int file);

-：生成一个黑心圆.

-#：指定按顺序标记。

收集整理了一份《2024年最新物联网嵌入式全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升的朋友。

如果你需要这些资料，可以戳这里获取

需要这些体系化资料的朋友，可以加我V获取：vip1024c （备注嵌入式）

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人

都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！

-：生成一个黑心圆.

-#：指定按顺序标记。

收集整理了一份《2024年最新物联网嵌入式全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升的朋友。
[外链图片转存中…(img-mcxzHOZ3-1715801977934)]
[外链图片转存中…(img-0zYpPCba-1715801977934)]

如果你需要这些资料，可以戳这里获取

需要这些体系化资料的朋友，可以加我V获取：vip1024c （备注嵌入式）

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人

都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！