Visual Studio C/C++函数/方法使用Doxygen格式注释

前言：Visual Studio默认使用的注释格式为xml格式注释，注释使用方法为在需要注释的函数/方法的上一行输入"///"后自动插入xml格式注释模板，具体示例如下代码块所示：

/// <summary>
/// Windows凭据提供程序登录交互函数
/// </summary>
/// <param name="pqcws">登录状态提示指针</param>
/// <returns>返回成功或失败</returns>
HRESULT FPKCredential::Connect(_In_  IQueryContinueWithStatus* pqcws)
{HRESULT hr = S_OK;IQueryContinueWithStatus* pStatus = pqcws;for (int i = 0; i < 10 && pStatus->QueryContinue() == S_OK; i++) {Sleep(1000); // 模拟耗时操作std::wstring progressMsg = L"进度: " + std::to_wstring((i + 1) * 10) + L"%";pStatus->SetStatusMessage(progressMsg.c_str());}return hr;
}

但大多数C/C++库默认使用的注释格式为Doxygen格式注释，如opencv库、pcl库等，因此C/C++开发者也更喜欢使用Doxygen格式的注释，而Visual Studio又是大多数C/C++开发者绕不开的一块IDE，故存在Visual Studio中使用Doxygen格式注释的需求。

实现方法：在Visual Studio中安装Doxygen Comment插件，如图所示（此处已经安装）：

安装插件完成后，在需要注释的函数上一行输入/**后回车或者输入/*!即可插入Doxygen格式的注释m模板，具体注释示例代码如下：

/*** Windows凭据提供程序登录交互函数.* * \param pqcws 登录状态提示指针* \return 返回成功或失败*/
HRESULT FPKCredential::Connect(_In_  IQueryContinueWithStatus* pqcws)
{HRESULT hr = S_OK;IQueryContinueWithStatus* pStatus = pqcws;for (int i = 0; i < 10 && pStatus->QueryContinue() == S_OK; i++) {Sleep(1000); // 模拟耗时操作std::wstring progressMsg = L"进度: " + std::to_wstring((i + 1) * 10) + L"%";pStatus->SetStatusMessage(progressMsg.c_str());}return hr;
}

其中，Doxygen Comment插件默认的函数参数与返回值的注释格式模板为\param、\return，此处可以自行修改为其它模板格式，如@param、@return格式，也可以进行更多形式的自定义，修改方法：工具->选项->Doxygen，然后根据个人需要的格式进行修改，如修改模板中的"\"为"@"、在函数说明前加入@brief等，具体如图所示：

函数/方法注释模板修改后为：

/*** $BRIEF$END.* * \param $PARAMS* \return $RETURN*/

函数/方法注释模板修改后为：

/*** @brief $BRIEF$END.* * @param $PARAMS* @return $RETURN*/

修改后注释格式如下示例代码所示：

/*** @brief Windows凭据提供程序登录交互函数.* * @param pqcws 登录状态提示指针* @return 返回成功或失败*/
HRESULT FPKCredential::Connect(_In_  IQueryContinueWithStatus* pqcws)
{HRESULT hr = S_OK;IQueryContinueWithStatus* pStatus = pqcws;for (int i = 0; i < 10 && pStatus->QueryContinue() == S_OK; i++) {Sleep(1000); // 模拟耗时操作std::wstring progressMsg = L"进度: " + std::to_wstring((i + 1) * 10) + L"%";pStatus->SetStatusMessage(progressMsg.c_str());}return hr;
}