ASPICE SWE3之——C代码生成软件详细设计2 注释格式

        写软件详细设计文档，一般多为有ASPICE要求，写文档真的很费时间，没有要求真的不想写。

        Doxygen工具就提供了一种通过给代码注释的方式，导出详细设计文档，至于导出什么内容，主要取决于注释的内容。比较好的一点是，里面会含有函数调用关系图。当然这里注释的格式是有要求的。

        要实现Doxygen工具生成详细设计文档，含有三个软件需要下载，我把安装包单独放资源里，有需要自取。

        另外ASPICE要求详设中的基本要包含以下内容，组件静态设计，组件动态设计，该组件追溯的架构ID，函数说明，该单元追溯的需求ID、各种变量的定义。具体讲起来挺多的，之后另开一个专题讲讲ASPICE，老写着写着就给自己后面留任务了(lll￢ω￢)。

        因为要详设内容齐全，要注释的东西会挺多，别怂，接着往下看。

        结合Doxygen注释格式的要求，以及ASPICE对详细设计内容的要求，制定此C代码注释规则。

        本规范的制订是为提高产品代码可读性，建立软件工程师使用C代码进行功能开发时注释的重要基本规则，便于使用Doxygen工具生成详细设计说明书，且统一注释风格利于后期维护及团队协作。

1、文件头注释格式

编译器差异中文注释从Dxygen导出报告可能会出现乱码，最好使用英文注释。当然百度也能解决。

文件头注释放在文件的首行。

注意：其中

* @author 作者

* @date 创建日期

记录最初编辑的作者和日期，后面有软件变更时不用变，仅在最下面的表格中记录软件变更履历。

* @version                当前版本

版本中记录最新变更后的版本号。

文件头格式

1 2 3 4 5 6

/** * @file 文件名（*.h/*.c） * @brief 该模块功能的简介 * @details               该模块功能的详细说明 * @author 作者（first author） * @date 创建日期（first date） * @version        当前版本 * @par Copyright *   Copyright(c) TECH * @par Hardware Version *   对应的硬件版本号 * @par SW component ID *   对应的软件架构中的组件ID * @par History * <table> * <tr><th>Date        <th>Version    <th>Author   <th>Description * <tr><td>创建日期    <td>版本号      <td>作者      <td>说明 * </table> */

示例：

1 2 3 4 5 6

/**  * @file        MMM.c  * @brief       UV diagnosis  * @details       The error is established if the voltage is lower than 2V  * @author       DDD  * @date       2023/4/7  * @version       1.0  * @par Copyright  *   Copyright(c)  AAA  * @par Hardware Version  *   AAAA  * @par SW component ID  *   SWC001  * @par History  * <table>  * <tr><th>Date        <th>Version    <th>Author      <th>Description  * <tr><td>2023/4/7    <td>1.0      <td>DDD     <td>fist version  * </table> */

2、函数注释格式

函数注释放在函数的上面

注意：所有单独注释的格式为

/**

 *

 */

其中，以下函数头注释格式为基本注释格式，根据函数实际包含的内容选择性进行注释，没有的部分（如return等）可删掉。

函数头格式

1 2 3 4 5 6 7 8

/**   * @brief 简述函数功能   * @details 函数详细说明   * @param[in]  参数名 Type:数据类型  参数注解   * @param[out]  参数名 Type:数据类型  参数注解   * @return 返回变量   *   @retval 返回值   * @note 提示一些注意事项或必要的技术细节   * @par SW Unit ID   *    对应的软件单元ID   * @par Ref SW Requirement ID   *    关联的软件需求ID   */

示例：

1 2 3 4 5 6 7 8

/**  * @brief            get the voltage and unit conversion  * @details         Convert the voltage variable unit from V to mV  * @param[in]    U_x      Type:unsigned short unit:V  * @param[out]   V_1    Type:unsigned short  voltage,x=1~4,unit:mV  * @note         The function  is to provide input conditions for the determination of  UV fault.  * @par SW Unit ID  *     SWU_001  * @par Ref SW Requirement ID  *     SWER_001_001  */

3、宏定义注释格式

放在每个宏定义后面。

注意：///<为注释前面的代码，///为注释后面的代码

宏定义格式

1 2 3 4 5

#define CELL_UV_LIMIT  (2000) ///<UV threshold value(mv) #define CELL_NV_LIMIT  (2000) ///<UV recovery threshold value(mv) #define CELL_UV_TURE   (1) ///<UV diagnosis mature 1

4、变量注释格式

在变量定义前做变量说明，在每个变量后属性说明

变量定义格式

1 2 3 4 5

/**  * @brief  Component external input interface  */ extern unsigned short U_1;  ///<Initial:0  range:[0,4]  Factor:1  Offset:0  Unit:V extern unsigned short U_2;  ///<Initial:0  range:[0,4]  Factor:1  Offset:0  Unit:V

5、枚举、结构体注释格式

结构体注释格式同以下枚举注释格式。

枚举量定义格式

1 2 3 4 5 6 7 8 9

/**  *  @brief status type for test Status  */ enum TestStatus {      TEST_STATUS_STOP,  ///< enum test stoped      TEST_STATUS_START, ///< enum test started };

6、类型定义注释格式

类型定义格式

1 2 3 4 5

/**  *  @brief define MWPBool type as int base type  */ typedef int MWPBool