【Qt 学习之路】Qt Creator自定义注释功能

目录

1、简述

2、配置

3、自动补全键

4、C++ 文件注释模板

4.1、文件注释

4.2、函数注释

4.3、结构体注释

4.4、变量注释

---

1、简述

Qt有很强大的注释功能，一般人只知道“Ctrl+I”的快捷键。

研究过这个的，还会用doxygen插件注释。其实Qt本身提供了很强大的注释功能，不用自己瞎搞些麻烦的事儿。

比如你想在class前说明一下这个类的作用，你可以把光标定位在class的上一行的空白处：

按一下“/”，再按两个“**”，再按一次回车，你发现了什么？注释就这么简单。

/**
 * @brief MainWindow::~MainWindow
 */
MainWindow::~MainWindow()
{
    delete ui;
}

2、配置

在写代码的时候我们为了规范化，一般会加文件注释、类注释和函数注释；用注释来说明我们的代码，也方便模块化开发，那么我们在写注释的时候经常会写一些重复的内容，我们会复制粘贴。这样一来二去，就显得很繁琐。

说明性文件（例如：.h 文件、.inc 文件、.def 文件等）头部应进行注释，注释一般需要列出：

版权说明生成日期作者功能

下面介绍QtCreator自定义的注释配置。

假如你的工程很多，项目很多又很繁杂，那么自定义注释功能正好用的上。

打开QtCreator的“工具”，“选项”，“文本编辑器”，“片段”，“添加”：

如图是我自定义的注释字母“z”，如果你没有像我一样自定义自动补全键，那么最好别设置一位字母，因为Qt默认的自动补全是从第三位开始的。所以你如果没设置自动补全键，就设置三位以上的字母吧！添加完，就可以在程序中用了，不用重启Qt。
 
成功的话，如下图：

按一下自定义的字母，然后按自动补全键，就看到自己的注释了吧，然后按一下回车就OK了。
很简单吧！

3、自动补全键

在用Qt编程的时，它默认是以“CTRL+空格”来作为自动补全的快捷键的，但是这样会与某些输入法的快捷键冲突。

所以，这个“Ctrl+空格”快捷键就不起作用了，那么我们重新设置下它的快捷键就解决了这个问题。

打开Qt，点击“工具”，在点击“选项”中，出现如图画面，照我的图依次点击即可：

这样我们就将自动补全键设置为“shift+空格”了。
 
这样做的目的是为了快速补全。因为Qt默认的自动补全是在第三位字母输入后才开始提示补全的，如果我们自定义完后，在我们输入1位字母后，如果有补全的信息，按一下自动补全键就会提示补全了。

4、C++ 文件注释模板

4.1、文件注释

以下是文件顶部注释模板，主要内部包括版权说明、文件名、该文件中的主要功能、版本号、文件创建者、时间等内容。实际注释中不包括（1）（2）编号说明。

/***************************************************************
 * Copyright(C) 2018,Company All Rights Reserved (1)版权说明
 * 
 * @file    : CSqlManager.cpp (2) 文件名
 * 
 * @brief   :  sql数据库管理类 (3) 该文件主要功能简介
 * 
 * @version : 1.0 (4) 版本信息
 * 
 * @author  : 沙振宇 (5) 创建作者
 * 
 * @date    : 2018/12/28 星期五
 * 
 * Details  :
 ***************************************************************/

4.2、函数注释

在项目中函数注释是最常见的一种注释，主要包括函数作用、函数参数说明、返回值、时间和作者信息。其函数注释模板如下：

/**************************************************************
*  @brief : CADOManager::InitADOConn
*     
*  @param : 
*     
*    -const STRU_CONN_SQL_INFO& stSqlInfo
*     
*    -unsigned int timeout
*     
*  @return : BOOL
*     
*  @author : 沙振宇
*     
*  @date : 2018/12/22 星期六
*     
*  @note : 
***************************************************************/

4.3、结构体注释

对结构体成员右边进行函数说明，为了美观最好注释对齐，模板如下：

typedef struct
{
    std::wstring strHost;       /*主机地址*/
    std::wstring strPort;       /*数据库端口*/
    std::wstring strUserName;   /*用户名*/
    std::wstring strPassword;   /*密码*/
    std::wstring strDBName;     /*待校验的数据库*/
}STRU_CONN_SQL_INFO;

4.4、变量注释

一般而言，主要是全局变量或者特殊变量才会进行注释，否则通过变量合理命名的形式进行自注释,模板格式如下：

//数据库名字
std::wstring strDBName;