From b21f2efa91fb601363a7535ecd9367a4b1aa5866 Mon Sep 17 00:00:00 2001 From: Simon Rozman Date: Mon, 7 Mar 2022 10:10:16 +0100 Subject: [PATCH] Doxygen: Unify group definitions and add \files Signed-off-by: Simon Rozman --- include/WinStd/COM.h | 13 ++++++---- include/WinStd/Common.h | 50 ++++++++++++++++++++++----------------- include/WinStd/Cred.h | 11 +++++---- include/WinStd/Crypt.h | 11 +++++---- include/WinStd/EAP.h | 11 +++++---- include/WinStd/ETW.h | 11 +++++---- include/WinStd/GDI.h | 11 +++++---- include/WinStd/MSI.h | 10 ++++---- include/WinStd/Sec.h | 11 +++++---- include/WinStd/SetupAPI.h | 11 +++++---- include/WinStd/Shell.h | 11 +++++---- include/WinStd/WLAN.h | 17 ++++++++----- include/WinStd/Win.h | 11 +++++---- include/WinStd/WinSock2.h | 11 +++++---- include/WinStd/WinTrust.h | 11 +++++---- 15 files changed, 131 insertions(+), 80 deletions(-) diff --git a/include/WinStd/COM.h b/include/WinStd/COM.h index edbfb73e..b9d5160c 100644 --- a/include/WinStd/COM.h +++ b/include/WinStd/COM.h @@ -4,6 +4,14 @@ Copyright © 2016 GÉANT */ +/// \file +/// Provides helper templates for Windows COM object manipulation +/// +/// \defgroup WinStdCOM COM object management +/// +/// Provides helper templates for Windows COM object manipulation +/// + #pragma once #include "Common.h" @@ -46,10 +54,7 @@ namespace winstd /// @} - /// - /// \defgroup WinStdCOM COM object management - /// Provides helper templates for Windows COM object manipulation - /// + /// \addtogroup WinStdCOM /// @{ /// diff --git a/include/WinStd/Common.h b/include/WinStd/Common.h index e76621f6..e9111afb 100644 --- a/include/WinStd/Common.h +++ b/include/WinStd/Common.h @@ -16,10 +16,32 @@ #include #include +/// \file +/// General API /// /// \defgroup WinStdGeneral General /// General API /// +/// \defgroup WinStdStrFormat String Formatting +/// Formatted string generation +/// +/// \par Example +/// \code +/// // Please note the PCSTR typecasting invokes an operator to return +/// // pointer to formatted buffer rather than class reference itself. +/// cout << (PCSTR)(winstd::string_printf("%i is less than %i.\n", 1, 5)); +/// \endcode +/// +/// \defgroup WinStdSysHandles System Handles +/// Simplifies work with object handles of various type +/// +/// \defgroup WinStdExceptions Exceptions +/// Additional exceptions +/// +/// \defgroup WinStdMemSanitize Auto-sanitize Memory Management +/// Sanitizes memory before dismissed + +/// \addtogroup WinStdGeneral /// @{ /// @@ -81,16 +103,7 @@ private: \ /// @} -/// \defgroup WinStdStrFormat String Formatting -/// Formatted string generation -/// -/// \par Example -/// \code -/// // Please note the PCSTR typecasting invokes an operator to return -/// // pointer to formatted buffer rather than class reference itself. -/// cout << (PCSTR)(winstd::string_printf("%i is less than %i.\n", 1, 5)); -/// \endcode -/// +/// \addtogroup WinStdStrFormat /// @{ /// @@ -149,10 +162,7 @@ private: \ /// @} -/// -/// \defgroup WinStdSysHandles System Handles -/// Simplifies work with object handles of various type -/// +/// \addtogroup WinStdSysHandles /// @{ /// @@ -187,10 +197,12 @@ private: #define _FormatMessage_format_string_ _In_z_ #endif +/// \cond internal #ifndef _LPCBYTE_DEFINED #define _LPCBYTE_DEFINED typedef const BYTE *LPCBYTE; #endif +/// \endcond #pragma warning(push) // Do not use _vsnprintf_s/_vsnwprintf_s(), since it terminates string by force even when we explicitly want to write unterminated string. @@ -988,10 +1000,7 @@ namespace winstd /// @} - /// - /// \defgroup WinStdExceptions Exceptions - /// Additional exceptions - /// + /// \addtogroup WinStdExceptions /// @{ /// @@ -1400,10 +1409,7 @@ namespace winstd /// @} - /// - /// \defgroup WinStdMemSanitize Auto-sanitize Memory Management - /// Sanitizes memory before dismissed - /// + /// \addtogroup WinStdMemSanitize /// @{ // winstd::sanitizing_allocator::destroy() member generates _Ptr parameter not used warning for primitive datatypes _Ty. diff --git a/include/WinStd/Cred.h b/include/WinStd/Cred.h index b3ee9328..5756bb33 100644 --- a/include/WinStd/Cred.h +++ b/include/WinStd/Cred.h @@ -4,16 +4,19 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft Credentials API +/// +/// \defgroup WinStdCredAPI Credentials API +/// Integrates WinStd classes with Microsoft Credentials API + #pragma once #include "Common.h" #include #include -/// -/// \defgroup WinStdCredAPI Credentials API -/// Integrates WinStd classes with Microsoft Credentials API -/// +/// \addtogroup WinStdCredAPI /// @{ /// @copydoc CredProtectW() diff --git a/include/WinStd/Crypt.h b/include/WinStd/Crypt.h index e15916d3..2564f354 100644 --- a/include/WinStd/Crypt.h +++ b/include/WinStd/Crypt.h @@ -4,6 +4,12 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft Cryptography API +/// +/// \defgroup WinStdCryptoAPI Cryptography API +/// Integrates WinStd classes with Microsoft Cryptography API + #pragma once #include "Common.h" @@ -13,10 +19,7 @@ #include #include -/// -/// \defgroup WinStdCryptoAPI Cryptography API -/// Integrates WinStd classes with Microsoft Cryptography API -/// +/// \addtogroup WinStdCryptoAPI /// @{ /// @copydoc CertGetNameStringW() diff --git a/include/WinStd/EAP.h b/include/WinStd/EAP.h index 72a01025..be7c5cd3 100644 --- a/include/WinStd/EAP.h +++ b/include/WinStd/EAP.h @@ -4,6 +4,12 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft EAP API +/// +/// \defgroup WinStdEAPAPI Extensible Authentication Protocol API +/// Integrates WinStd classes with Microsoft EAP API + #pragma once #include "Common.h" @@ -21,10 +27,7 @@ #pragma warning(push) #pragma warning(disable: 4505) // Don't warn on unused code -/// -/// \defgroup WinStdEAPAPI Extensible Authentication Protocol API -/// Integrates WinStd classes with Microsoft EAP API -/// +/// \addtogroup WinStdEAPAPI /// @{ /// diff --git a/include/WinStd/ETW.h b/include/WinStd/ETW.h index c1bb02d0..a21c931e 100644 --- a/include/WinStd/ETW.h +++ b/include/WinStd/ETW.h @@ -4,6 +4,12 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Event Tracing for Windows API +/// +/// \defgroup WinStdETWAPI Event Tracing for Windows API +/// Integrates WinStd classes with Event Tracing for Windows API + #pragma once #include "Common.h" @@ -19,10 +25,7 @@ #pragma warning(push) #pragma warning(disable: 4505) // Don't warn on unused code -/// -/// \defgroup WinStdETWAPI Event Tracing for Windows API -/// Integrates WinStd classes with Event Tracing for Windows API -/// +/// \addtogroup WinStdETWAPI /// @{ /// diff --git a/include/WinStd/GDI.h b/include/WinStd/GDI.h index 2f1aa0a2..d836037b 100644 --- a/include/WinStd/GDI.h +++ b/include/WinStd/GDI.h @@ -3,16 +3,19 @@ Copyright © 1991-2022 Amebis */ +/// \file +/// Integrates WinStd classes with Microsoft Windows GDI +/// +/// \defgroup WinStdGdiAPI GDI API +/// Integrates WinStd classes with Microsoft Windows GDI + #pragma once #include "Common.h" namespace winstd { - /// - /// \defgroup WinStdGdiAPI GDI API - /// Integrates WinStd classes with Microsoft Windows GDI - /// + /// \addtogroup WinStdGdiAPI /// @{ /// diff --git a/include/WinStd/MSI.h b/include/WinStd/MSI.h index 168af330..47692dc5 100644 --- a/include/WinStd/MSI.h +++ b/include/WinStd/MSI.h @@ -4,6 +4,12 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft Installer API +/// +/// \defgroup WinStdMSIAPI Microsoft Installer API +/// Integrates WinStd classes with Microsoft Installer API + #pragma once #include "Common.h" @@ -11,10 +17,6 @@ #include #include -/// -/// \defgroup WinStdMSIAPI Microsoft Installer API -/// Integrates WinStd classes with Microsoft Installer API -/// /// \addtogroup WinStdMSIAPI /// @{ diff --git a/include/WinStd/Sec.h b/include/WinStd/Sec.h index 5481d23d..0b02e643 100644 --- a/include/WinStd/Sec.h +++ b/include/WinStd/Sec.h @@ -4,16 +4,19 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft Security API +/// +/// \defgroup WinStdSecurityAPI Security API +/// Integrates WinStd classes with Microsoft Security API + #pragma once #include "Common.h" #include #include -/// -/// \defgroup WinStdSecurityAPI Security API -/// Integrates WinStd classes with Microsoft Security API -/// +/// \addtogroup WinStdSecurityAPI /// @{ #if defined(SECURITY_WIN32) || defined(SECURITY_KERNEL) diff --git a/include/WinStd/SetupAPI.h b/include/WinStd/SetupAPI.h index b96dcc7d..bcb681a7 100644 --- a/include/WinStd/SetupAPI.h +++ b/include/WinStd/SetupAPI.h @@ -4,6 +4,12 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft Setup API +/// +/// \defgroup SetupAPI Setup API +/// Integrates WinStd classes with Microsoft Setup API + #pragma once #include "Common.h" @@ -11,10 +17,7 @@ namespace winstd { - /// - /// \defgroup SetupAPI Setup API - /// Integrates WinStd classes with Microsoft Setup API - /// + /// \addtogroup SetupAPI /// @{ /// diff --git a/include/WinStd/Shell.h b/include/WinStd/Shell.h index c2ad58c5..e3c72688 100644 --- a/include/WinStd/Shell.h +++ b/include/WinStd/Shell.h @@ -4,16 +4,19 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft Shell API +/// +/// \defgroup WinStdShellWAPI Shell API +/// Integrates WinStd classes with Microsoft Shell API + #pragma once #include "Common.h" #include #include -/// -/// \defgroup WinStdShellWAPI Shell API -/// Integrates WinStd classes with Microsoft Shell API -/// +/// \addtogroup WinStdShellWAPI /// @{ /// @copydoc PathCanonicalizeW() diff --git a/include/WinStd/WLAN.h b/include/WinStd/WLAN.h index f2f0aafa..0eb70c3f 100644 --- a/include/WinStd/WLAN.h +++ b/include/WinStd/WLAN.h @@ -4,21 +4,26 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft WLAN API +/// +/// \defgroup WinStdWLANAPI WLAN API +/// Integrates WinStd classes with Microsoft WLAN API + #pragma once #include "Common.h" #include #include +/// \addtogroup WinStdWLANAPI +/// @{ + +/// \cond internal // Must not statically link to Wlanapi.dll as it is not available on Windows // without a WLAN interface. extern DWORD (WINAPI *pfnWlanReasonCodeToString)(__in DWORD dwReasonCode, __in DWORD dwBufferSize, __in_ecount(dwBufferSize) PWCHAR pStringBuffer, __reserved PVOID pReserved); - -/// -/// \defgroup WinStdWLANAPI WLAN API -/// Integrates WinStd classes with Microsoft WLAN API -/// -/// @{ +/// \endcond /// /// Retrieves a string that describes a specified reason code and stores it in a std::wstring string. diff --git a/include/WinStd/Win.h b/include/WinStd/Win.h index 0f57ca4d..8142671a 100644 --- a/include/WinStd/Win.h +++ b/include/WinStd/Win.h @@ -4,6 +4,12 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft Windows API +/// +/// \defgroup WinStdWinAPI Windows API +/// Integrates WinStd classes with Microsoft Windows API + #pragma once #include "Common.h" @@ -13,10 +19,7 @@ #pragma warning(push) #pragma warning(disable: 4505) // Don't warn on unused code -/// -/// \defgroup WinStdWinAPI Windows API -/// Integrates WinStd classes with Microsoft Windows API -/// +/// \addtogroup WinStdWinAPI /// @{ /// @copydoc GetModuleFileNameW() diff --git a/include/WinStd/WinSock2.h b/include/WinStd/WinSock2.h index 675d7fd7..2b77515c 100644 --- a/include/WinStd/WinSock2.h +++ b/include/WinStd/WinSock2.h @@ -4,6 +4,12 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft WinSock2 API +/// +/// \defgroup WinSock2API WinSock2 API +/// Integrates WinStd classes with Microsoft WinSock2 API + #pragma once #include "Common.h" @@ -13,10 +19,7 @@ namespace winstd { - /// - /// \defgroup WinSock2API WinSock2 API - /// Integrates WinStd classes with Microsoft WinSock2 API - /// + /// \addtogroup WinSock2API /// @{ /// diff --git a/include/WinStd/WinTrust.h b/include/WinStd/WinTrust.h index 7f385178..19e641ac 100644 --- a/include/WinStd/WinTrust.h +++ b/include/WinStd/WinTrust.h @@ -4,6 +4,12 @@ Copyright © 2016 GÉANT */ +/// \file +/// Integrates WinStd classes with Microsoft WinTrust API +/// +/// \defgroup WinTrustAPI WinTrust API +/// Integrates WinStd classes with Microsoft WinTrust API + #pragma once #include "Common.h" @@ -11,10 +17,7 @@ namespace winstd { - /// - /// \defgroup WinTrustAPI WinTrust API - /// Integrates WinStd classes with Microsoft WinTrust API - /// + /// \addtogroup WinTrustAPI /// @{ ///