Doxygen: Unify group definitions and add \files

Signed-off-by: Simon Rozman <simon@rozman.si>

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
 
     /// @}
 
-    ///
+    /// \addtogroup WinStdCOM
-    /// \defgroup WinStdCOM COM object management
-    /// Provides helper templates for Windows COM object manipulation
-    ///
     /// @{
 
     ///

include/WinStd/Common.h

@@ -16,10 +16,32 @@
 #include <string>
 #include <vector>
 
+/// \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
+/// \addtogroup WinStdStrFormat
-/// 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
-///
 /// @{
 
 ///
@@ -149,10 +162,7 @@ private: \
 
 /// @}
 
-///
+/// \addtogroup WinStdSysHandles
-/// \defgroup WinStdSysHandles System Handles
-/// Simplifies work with object handles of various type
-///
 /// @{
 
 ///
@@ -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
 
     /// @}
 
-    ///
+    /// \addtogroup WinStdExceptions
-    /// \defgroup WinStdExceptions Exceptions
-    /// Additional exceptions
-    ///
     /// @{
 
     ///
@@ -1400,10 +1409,7 @@ namespace winstd
 
     /// @}
 
-    ///
+    /// \addtogroup WinStdMemSanitize
-    /// \defgroup WinStdMemSanitize Auto-sanitize Memory Management
-    /// Sanitizes memory before dismissed
-    ///
     /// @{
 
     // winstd::sanitizing_allocator::destroy() member generates _Ptr parameter not used warning for primitive datatypes _Ty.

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 <wincred.h>
 #include <memory>
 
-///
+/// \addtogroup WinStdCredAPI
-/// \defgroup WinStdCredAPI Credentials API
-/// Integrates WinStd classes with Microsoft Credentials API
-///
 /// @{
 
 /// @copydoc CredProtectW()

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 <string>
 #include <vector>
 
-///
+/// \addtogroup WinStdCryptoAPI
-/// \defgroup WinStdCryptoAPI Cryptography API
-/// Integrates WinStd classes with Microsoft Cryptography API
-///
 /// @{
 
 /// @copydoc CertGetNameStringW()

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
 
-///
+/// \addtogroup WinStdEAPAPI
-/// \defgroup WinStdEAPAPI Extensible Authentication Protocol API
-/// Integrates WinStd classes with Microsoft EAP API
-///
 /// @{
 
 ///

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
 
-///
+/// \addtogroup WinStdETWAPI
-/// \defgroup WinStdETWAPI Event Tracing for Windows API
-/// Integrates WinStd classes with Event Tracing for Windows API
-///
 /// @{
 
 ///

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
 {
-    ///
+    /// \addtogroup WinStdGdiAPI
-    /// \defgroup WinStdGdiAPI GDI API
-    /// Integrates WinStd classes with Microsoft Windows GDI
-    ///
     /// @{
 
     ///

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 <string>
 #include <vector>
 
-///
-/// \defgroup WinStdMSIAPI Microsoft Installer API
-/// Integrates WinStd classes with Microsoft Installer API
-///
 /// \addtogroup WinStdMSIAPI
 /// @{
 

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 <Security.h>
 #include <string>
 
-///
+/// \addtogroup WinStdSecurityAPI
-/// \defgroup WinStdSecurityAPI Security API
-/// Integrates WinStd classes with Microsoft Security API
-///
 /// @{
 
 #if defined(SECURITY_WIN32) || defined(SECURITY_KERNEL)

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
 {
-    ///
+    /// \addtogroup SetupAPI
-    /// \defgroup SetupAPI Setup API
-    /// Integrates WinStd classes with Microsoft Setup API
-    ///
     /// @{
 
     ///

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 <Shlwapi.h>
 #include <string>
 
-///
+/// \addtogroup WinStdShellWAPI
-/// \defgroup WinStdShellWAPI Shell API
-/// Integrates WinStd classes with Microsoft Shell API
-///
 /// @{
 
 /// @copydoc PathCanonicalizeW()

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 <wlanapi.h>
 #include <string>
 
+/// \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);
-
+/// \endcond
-///
-/// \defgroup WinStdWLANAPI WLAN API
-/// Integrates WinStd classes with Microsoft WLAN API
-///
-/// @{
 
 ///
 /// Retrieves a string that describes a specified reason code and stores it in a std::wstring string.

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
 
-///
+/// \addtogroup WinStdWinAPI
-/// \defgroup WinStdWinAPI Windows API
-/// Integrates WinStd classes with Microsoft Windows API
-///
 /// @{
 
 /// @copydoc GetModuleFileNameW()

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
 {
-    ///
+    /// \addtogroup WinSock2API
-    /// \defgroup WinSock2API WinSock2 API
-    /// Integrates WinStd classes with Microsoft WinSock2 API
-    ///
     /// @{
 
     ///

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
 {
-    ///
+    /// \addtogroup WinTrustAPI
-    /// \defgroup WinTrustAPI WinTrust API
-    /// Integrates WinStd classes with Microsoft WinTrust API
-    ///
     /// @{
 
     ///