基于Doxygen的C/C++注释原则

来源：互联网发布：淘宝玉兰油沐浴露编辑：程序博客网时间：2024/05/15 10:32

基于Doxygen的C/C++注释原则标注总述1.文件头标注2. 命名空间标注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 + (r) * 306) >> 10 )//---------------------------------------------------------------------------// date and time at compile time//---------------------------------------------------------------------------#define OST_TIMESTAMP                __DATE__ " " __TIME__1. 文件头的标注/******************************************************************************  OpenST Basic tool library                                                 **  Copyright (C) 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 :                                                          **  <Date>     | <Version> | <Author>       | <Description>                   **----------------------------------------------------------------------------**  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 返回说明    *        -<em>false</em> fail    *        -<em>true</em> 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);        -：生成一个黑心圆.    -#：指定按顺序标记。    ::：指定连接函数功能。（注：空格和“:”有连接功能,但建议还是使用”::”。只对函数有用。）    它们格式如下: (-和::例子前面有了,就介绍-#例子。)            - 简要说明            -# 简要说明            ::函数名    例：     /**      * @param [in] person 只能输入以下参数：      * -# a:代表张三        // 生成 1. a:代表张三      * -# b:代表李四        // 生成 2. b:代表李四      * -# c:代表王二        // 生成 3. c:代表王二    */    void GetPerson(int p);    5. 变量注释    /// 简述    /** 详细描述. */    或者    //! 简述    //! 详细描述    //! 从这里开始    int m_variable_1; ///< 成员变量m_variable_1说明    int m_variable_2; ///< 成员变量m_variable_1说明      /**  * @brief 成员变量m_c简要说明  *  * 成员变量m_variable_3的详细说明，这里可以对变量进行  * 详细的说明和描述，具体方法和函数的标注是一样的  */  bool m_variable_3;    如果变量需要详细说明的可已按照m_varibale_3的写法写，注意，m_variable_2和m_variable_3之间一定需要空行，否则会导致m_variable_2的简述消失    6. 模块标注        模块定义格式:            /**            * @defgroup 模块名  页的标题名 (模块名只能英文,这个可以随便取.在一个源文件里不能相同)            * @{ (跟c语言{一样起作用域功能)            */            … 定义的内容 …            /** @} */                        例：            /**            * @defgroup HenryWen Example.cpp            * @{            */              … 定义的内容 …            /** @} */    7. 分组标注        分组定义格式：            /**            * @name 分组说明文字            * @{            */            … 定义的内容 …            /** @} */                        例：            /**            * @name PI常量            * @{            */            #define PI 3.1415926737            /** @} */                        /**            * @name 数组固定长度常量            * @{            */            const int g_ARRAY_MAX = 1024;            /** @} */

0 0