常用的指令说明：
@file 档案的批注说明。 @author 作者的信息 @brief 用于class 或function的简易说明 eg ： @brief 本函数负责打印错误信息串 @param 主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明 @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 本函数执行可能会产生超出范围的异常
一 概述C++的注释风格主要使用下面这种样式：即在注释块开始使用三个反斜杠‘/’其他地方其实与JavaDoc的风格类似，只是C++风格不用 “*” 罢了。二 简述与详述C++风格的简述与详述方式与javaDoc类似。一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容，C++风格可以使用的分隔方法有以下两种：（1）使用 /brief 参数标识，空行作为简述和详述的间隔标识 /// /brief Brief description. /// description continued. /// /// Detailed description starts here. /// （2） 使用以空行（或者小数点加空格）作为简述与详述的分割 /// Brief description /// description continued. /// /// Detailed description starts here. 以小数点加空格作为分隔如下：/// Brief description /// description continued . （注意:这里有一个小数点,加上一个空格） /// Detailed description starts here. /// 三 注释风格约定1. 一个代码块（类、函数、结构等）的概述采用单行的”///”加一个空格开头的注释，并写在该代码块声明的前面；2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释，若不足两行第二行的开头也要写出来，并且放在代码块定义的前面；如果某代码没有声明只有定义或者相反，则在定义或者声明前面写上单行的概述+一个空行+多行的详述；3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释；4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释（相当于是给改变量一个概述）；5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面；6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面；7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面；8. 文件头的版权以及文件描述的注释参见例代码。四 文件头注释示例// /// COPYRIGHT NOTICE /// Copyright (c) 2009, 华中科技大学 （版权声明） /// All rights reserved. /// /// @file （本文件的文件名eg：Test.h） /// @brief （本文件实现的功能的简述） /// ///（本文件实现的功能的详述） /// /// @version 1.1 （版本声明） /// @author （作者，eg：卢俊） /// @date （文件创建日期，eg：2009年7月15日） /// /// /// 修订说明：最初版本 // 五 类定义注释示例/// 本类的功能：打印错误信息 /// /// 本类是一个单件 /// 在程序中需要进行错误信息打印的地方 class CPrintError { …… } 5.4.6 类成员变量定义示例（1）在成员变量上面加注释的格式 /// 成员变量描述 int m_Var; （2）在成员变量后面加注释的格式 int m_color; /// 颜色变量 5.4.7 成员函数的注释示例/// 下面是一个含有两个参数的函数的注释说明（简述） /// /// 这里写该函数的详述信息 /// @param a 被测试的变量（param描述参数） /// @param s 指向描述测试信息的字符串 /// @return 测试结果 （return描述返回值） /// @see Test() （本函数参考其它的相关的函数，这里作一个链接） /// @note (note描述需要注意的问题) int testMe(int a,const char *s); 5.4.8 枚举变量的注释示例 /// 颜色的枚举定义 /// /// 该枚举定义了系统中需要用到的颜色/n /// 可以使用该枚举作为系统中颜色的标识 enum TEnum { RED, ///< 枚举，标识红色 BLUE, ///< 枚举，标志蓝色 YELLOW ///< 枚举，标志黄色. }enumVar; 六 需要注意的问题（1）Doxygen会忽略你在注释中加入的多余的换行，如果你希望保留两行注释之间的空行，那么，在该行加入 /n
C++ 举例
// -*- C++ -*- //========================================================================== /** * @file ARGV.h * * ARGV.h,v 4.36 2005/10/28 16:14:51 ossama Exp * * @author Doug Schmidt <schmidt@cs.wustl.edu> * @author Everett Anderson <eea1@cs.wustl.edu> */ //========================================================================== #ifndef ACE_ARGUMENT_VECTOR_H #define ACE_ARGUMENT_VECTOR_H #include /**/ "ace/pre.h" #include "ace/ACE_export.h" #if !defined (ACE_LACKS_PRAGMA_ONCE) # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ #include "ace/Unbounded_Queue.h" // Open versioned namespace, if enabled by the user. ACE_BEGIN_VERSIONED_NAMESPACE_DECL /** * @class ACE_ARGV * * @brief Builds a counted argument vector (ala argc/argv) from either * a string or a set of separate tokens. Can substitute environment * variable values for tokens that are environment variable references. */ class ACE_Export ACE_ARGV { public: // = Initialization and termination. /** * Splits the specified string into an argument vector, split at whitespace. * * @param buf An ACE_TCHAR array to split into tokens for the vector. * * @param substitute_env_args If non-zero, any token that is an * an environment variable reference ($VAR) will have * its environment variable value in the resultant vector * in place of the environment variable name. This only works * if the token is an environment variable reference and * nothing else; it doesn't substitute environment variable * references within a token. For example, @c $HOME/file will * not substitute the value of the HOME environment variable. */ ACE_ARGV (const ACE_TCHAR buf[], int substitute_env_args = 1); /** * Converts @a argv into a linear string. If @a substitute_env_args * is enabled then we'll substitute the environment variables for * each $ENV encountered in the string. The <buf> operation is not * allowed on an ACE_ARGV created this way. */ ACE_ARGV (ACE_TCHAR *argv[], int substitute_env_args = 1); /** * Creates an ACE_ARGV which is the concatenation of the first_argv * and the second argv. The argv arguments should be null pointer * terminated. */ ACE_ARGV (ACE_TCHAR *first_argv[], ACE_TCHAR *second_argv[], int substitute_env_args =1); /** * Entry point for creating an ACE_TCHAR *[] command line * iteratively via the <add> method. When this constructor is used, * the <ITERATIVE> state is enabled. The <argv> and <buf> methods * are allowed, and the result is recreated when called multiple * times. The subscript operator is not allowed. */ ACE_ARGV (int substitute_env_args = 1); /// Destructor. ~ACE_ARGV (void); // = Accessor arguments. /// Returns the <index>th string in the ARGV array. const ACE_TCHAR *operator[] (size_t index); /** * Returns the @c argv array. Caller should not delete this memory * since the ACE_ARGV destructor will delete it. If the caller * modifies the array in the iterative mode, the changes are not * saved to the queue. */ ACE_TCHAR **argv (void); /// Returns @c argc. int argc (void) const; /// Returns the @c buf. Caller should not delete this memory since /// the ACE_ARGV destructor will delete it. const ACE_TCHAR *buf (void); /// Dump the state of an object. void dump (void) const; /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; /// Add another argument. This only works in the <ITERATIVE> state. /// Note that this method does not copy <next_arg>, nor does it /// assume ownership of managing its memory, i.e., the caller is /// responsible for memory management. Returns -1 on failure and 0 /// on success. int add (const ACE_TCHAR *next_arg); /** * Add another @a argv array. The @a argv parameter must be NULL * terminated. This only works in the <ITERATIVE> state. Returns * -1 on failure and 0 on success. */ int add (ACE_TCHAR *argv[]); /// What state is this ACE_ARGV in? int state (void) const; // These are the states possible via the different constructors. enum States { /// ACE_ARGV converts buf[] to ACE_TCHAR *argv[] TO_STRING = 1, /// ACE_ARGV converts ACE_TCHAR *argv[] to buf[] TO_PTR_ARRAY = 2, /// Builds buf[] or ACE_TCHAR *argv[] iteratively with <add>. ITERATIVE = 3 }; private: /// Copy Constructor not implemented ACE_ARGV (const ACE_ARGV&); /// Assignment '=' operator not implemented ACE_ARGV operator= (const ACE_ARGV&); /// Creates buf_ from the queue, deletes previous buf_. int create_buf_from_queue (void); /// Converts buf_ into the ACE_TCHAR *argv[] format. int string_to_argv (void); /// Returns the string created from argv in buf and /// returns the number of arguments. int argv_to_string (ACE_TCHAR **argv, ACE_TCHAR *&buf); /// Replace args with environment variable values? int substitute_env_args_; /// Current state marker. int state_; /// Number of arguments in the ARGV array. int argc_; /// The array of string arguments. ACE_TCHAR **argv_; /// Buffer containing the <argv> contents. ACE_TCHAR *buf_; /// Total length of the arguments in the queue, not counting /// separating spaces size_t length_; /// Queue which keeps user supplied arguments. This is only /// active in the "iterative" mode. ACE_Unbounded_Queue<ACE_TCHAR *> queue_; }; // Close versioned namespace, if enabled by the user. ACE_END_VERSIONED_NAMESPACE_DECL #if defined (__ACE_INLINE__) #include "ace/ARGV.inl" #endif /* __ACE_INLINE__ */ #include /**/ "ace/post.h" #endif /* ACE_ARGUMENT_VECTOR_H */
