代码注释规范(2)

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/donhao/article/details/6640096
 

2    注释规范要求

下面以C++中的头文件为例来说明如何进行注释,以及注释要求。

注意:由于blog显示原因,把其中的pre1改为pre,把b1改为b,删掉[注释*]字样。

/**
* @file example.h[注释1] 
* @brief 这是一个注释格式说明文件[注释2] 
* @author Wang Erxiao[注释3] 
* @author Si Maguang[注释4] 
* @date 2011-07-27 22:30:00[注释5] 
* @version 1.0[注释6] 
* <pre1><b1>Copyright (C) </b> 1998-2009 Comany Name </pre1>
* <pre1><b1>email:</b> hao.limin@gmail.com; simaguang@gmail.com[注释7] </pre1>
* <pre1><b1>company:</b>http://blog.csdn.net/donhao</pre1>
* <pre1><b1>All rights reserved.</b1></pre1>
* <pre1><b1>modification:</b1></pre1>
* <pre1>Write modifications here.</pre1>
[注释8] */

#include <string>

/** @brief枚举常量. */[注释9] 
typedef enum DayOfWeek
{
SUN = 0,     /**< 星期天 */[注释10] 
MON = 1,     /**< 星期一 */
TUE = 2,     /**< 星期二 */
WED = 3,     /**< 星期三 */
THU = 4,     /**< 星期四 */
FRI = 5,     /**< 星期五 */
SAT = 6      /**< 星期六 */
}

/**
* @class example
* @brief 封装了日志操作。
*
* detailed 基于网络的日志系统。
*/[注释11]

class example
{
public:

/**
* @brief Constructor for Example, 这里是简要描述,同时演示了\n
* 简要描述换行。
* 这里是详细描述,同时演示了\n
* 详细描述换行。
* @param configuationFilePath Defaults to "./ Example.conf". The path and
* file name of the configuration file.
*/

Example(std::string configuationFilePath = "./ Example.conf");

/** @brief Destructor for Example. */
~Example();

/**
* @defgroup Send_messages 这是Send_messages模块的Title
* @brief Send_messages模块的简要描述。
*
* Send_messages模块的详细描述。
* @{
*/[注释13] 

/**
* @brief 向系统发送一条Emergence级别的消息.
*
* emerg函数的详细描述。
* @param[in] message The content of the log message.
* @return bool
* @see log
* @note 注释
* @since 2008-10-10
* @exception LogException
* @deprecated
*/[注释14]
bool emerg(std::string message);
/** @} */ //Send_messages模块定义结束,其中包括一个函数。 

/**
* @addtogroup Send_messages
* @{[注释15]
*/ 

/**
* @brief Send a fatal log message to existing appenders.
* @param[out] message The content of the log message.
*/
void fatal(std::string message);

/**
* @brief Send an alert log message to existing appenders.
* @param[in] message The content of the log message.
* @return void
*/
void alert(std::string message);
/** @} */ //所要添加进的模块结束

/**
* @name gourp_name
* @brief gourp_name组的简要注释。
*
* gourp_name组的详细注释。
* @{
*/

/**
* @brief Send a notice log message to existing appenders.
* @param[in] message The content of the log message.
* @return void
*/
void notice(std::string message);
/** @} */ //组结束

/**
* @brief Send a log message with priority priorityLevel to existing appenders.
* @param[in] priorityLevel The priority of the log message.
* - LOG_EMERG       0
* - LOG_FATAL        1
* - LOG_ALERT       2
* - LOG_NOTICE      3
* - LOG_INFO         4[注释16]
* @param[in] message The content of the log message. 
* @return void
*/

void log(int priorityLevel, std::string message); 

/**
* @brief Get the message sending status.
* @return bool
*/

bool getSendStatus();

/**
* @file test.h
* @ingroup Send_messages
* @brief 添加文件test.h到Send_messages模块。
*/

[注释17] 

/**
* @namespace std
* @ingroup Send_messages
* @brief 添加命名空间std到Send_messages模块。
*/

[注释18] 

/**
* @class test
* @ingroup Send_messages
* @brief 添加类test到Send_messages模块。
*/
[注释19] 
};

 [注释1]文件名

 [注释2]在这里写文件描述。

 [注释3]作者姓名。注意@author和姓名之间要保持一个空格。

 [注释4]如果为多个作者,则另起一行在@author之后写上作者姓名。

 [注释5]日期。

 [注释6]代码版本。

 [注释7]作者邮箱。

 [注释8]可以根据具体需求来修改以上内容。

 [注释9]简要注释的格式。

 [注释10]成员注释的格式

 [注释11]类注释的格式,其中包括类名(自动生成)、简要注释、详细注释。

    1.       简要描述一定以@brief开始(自动生成)。

    2.       简要注释之后空一行才是详细注释。

 [注释12]注释换行的方法。

 [注释13]定义模块注释的方法,其模块结束标识为/** @} */

 [注释14]函数注释

 [注释15]将从此处至“/** @} */ //组结束”之前的内容添加至Send_messages模块中。

 [注释16]项目符号标记。

 [注释17]文件test.h属于模块Send_messages。

 [注释18]命名空间std属于模块Send_messages。

 [注释19]类test属于模块Send_messages。

没有更多推荐了,返回首页