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

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

/// <summary>
/// Windows凭据提供程序登录交互函数
/// </summary>
/// <param name="pqcws">登录状态提示指针</param>
/// <returns>返回成功或失败</returns>
HRESULT TestCredential::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 TestCredential::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;
}