From 21c1bf5084132d3780037005148931c2e14dbf8d Mon Sep 17 00:00:00 2001
From: Simon Rozman <simon@rozman.si>
Date: Fri, 4 Feb 2022 14:28:18 +0100
Subject: [PATCH] Doxygen: Address warnings

Signed-off-by: Simon Rozman <simon@rozman.si>
---
 Doxyfile                  | 27 ++++++++++++++++++++++++---
 include/WinStd/Common.h   | 32 +++++++++++++++++++++++++++-----
 include/WinStd/GDI.h      | 12 ++++++++++++
 include/WinStd/SetupAPI.h |  4 +++-
 include/WinStd/WinTrust.h |  2 ++
 5 files changed, 68 insertions(+), 9 deletions(-)

diff --git a/Doxyfile b/Doxyfile
index 72782a92..8d9f45eb 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -2198,7 +2198,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2206,7 +2206,7 @@ MACRO_EXPANSION        = NO
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2238,7 +2238,28 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = \
+    _FormatMessage_format_string_= \
+    _Frees_ptr_opt_= \
+    _In_= \
+    _In_bytecount_(x)= \
+    _In_count_(x)= \
+    _In_opt_= \
+    _In_opt_count_(x)= \
+    _In_opt_z_= \
+    _In_reads_(x)= \
+    _In_reads_opt_(x)= \
+    _In_z_= \
+    _In_z_count_(x)= \
+    _Inout_= \
+    _Inout_count_(x)= \
+    _Inout_opt_= \
+    _Out_= \
+    _Out_opt_= \
+    _Out_z_cap_(x)= \
+    _Printf_format_string_= \
+    _Reserved_= \
+    _Success_(x)=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
diff --git a/include/WinStd/Common.h b/include/WinStd/Common.h
index 0cbe22be..f82f776b 100644
--- a/include/WinStd/Common.h
+++ b/include/WinStd/Common.h
@@ -112,15 +112,39 @@ private: \
 #define PRINTF_LPOLESTR  "ls"
 #endif
 
+///
+/// Standard input stream for TCHAR strings
+///
 #ifdef _UNICODE
 #define _tcin   (std::wcin )
+#else
+#define _tcin   (std::cin ) ///< Standard input stream for TCHAR strings
+#endif
+
+///
+/// Standard output stream for TCHAR strings
+///
+#ifdef _UNICODE
 #define _tcout  (std::wcout)
+#else
+#define _tcout  (std::cout)
+#endif
+
+///
+/// Standard error stream for TCHAR strings
+///
+#ifdef _UNICODE
 #define _tcerr  (std::wcerr)
+#else
+#define _tcerr  (std::cerr)
+#endif
+
+///
+/// Standard logging stream for TCHAR strings
+///
+#ifdef _UNICODE
 #define _tclog  (std::wclog)
 #else
-#define _tcin   (std::cin )
-#define _tcout  (std::cout)
-#define _tcerr  (std::cerr)
 #define _tclog  (std::clog)
 #endif
 
@@ -821,8 +845,6 @@ namespace winstd
             }
         }
 
-        /// @}
-
     protected:
         ///
         /// Abstract member function that must be implemented by child classes to do the actual object destruction.
diff --git a/include/WinStd/GDI.h b/include/WinStd/GDI.h
index f4db9d64..2f1aa0a2 100644
--- a/include/WinStd/GDI.h
+++ b/include/WinStd/GDI.h
@@ -84,20 +84,32 @@ namespace winstd
     class window_dc : public handle<HDC, NULL>
     {
     public:
+        ///
+        /// Initializes an empty device context.
+        ///
         window_dc() noexcept :
             m_hwnd(NULL)
         {}
 
+        ///
+        /// Initializes a device context from existing data.
+        ///
         window_dc(_In_opt_ handle_type h, _In_opt_ HWND hwnd) noexcept :
             handle<handle_type, NULL>(h),
             m_hwnd(hwnd)
         {}
 
+        ///
+        /// Move an existing device context.
+        ///
         window_dc(_Inout_ window_dc &&h) noexcept :
             handle<handle_type, NULL>(std::move(h)),
             m_hwnd(h.m_hwnd)
         {}
 
+        ///
+        /// Copy an existing device context.
+        ///
         window_dc& operator=(_Inout_ window_dc &&h) noexcept
         {
             handle<handle_type, NULL>::operator=(std::move(h));
diff --git a/include/WinStd/SetupAPI.h b/include/WinStd/SetupAPI.h
index c27e203a..a7b941f9 100644
--- a/include/WinStd/SetupAPI.h
+++ b/include/WinStd/SetupAPI.h
@@ -144,10 +144,12 @@ namespace winstd
         }
 
     protected:
+        /// \cond internal
         HDEVINFO         m_DeviceInfoSet;
         PSP_DEVINFO_DATA m_DeviceInfoData;
         DWORD            m_DriverType;
-        BOOL             m_result;          ///< Did building succeed?
+        BOOL             m_result;
+        /// \endcond
     };
 
     /// @}
diff --git a/include/WinStd/WinTrust.h b/include/WinStd/WinTrust.h
index ab5c64c7..7f385178 100644
--- a/include/WinStd/WinTrust.h
+++ b/include/WinStd/WinTrust.h
@@ -49,9 +49,11 @@ namespace winstd
         }
 
     protected:
+        /// \cond internal
         HWND          m_hwnd;
         GUID          m_action;
         WINTRUST_DATA &m_wtd;
+        /// \endcond
     };
 
     /// @}