From d437ecc140bcb4b4e7394699026e6ad21b121ad1 Mon Sep 17 00:00:00 2001
From: yyc12345 <yyc12321@outlook.com>
Date: Mon, 27 May 2024 21:21:39 +0800
Subject: [PATCH] doc: add document for dialog helper

---
 src/DialogHelper.cpp | 30 ++++++++++++++++++++++++++++++
 src/DialogHelper.hpp | 20 +++++++++++++++++++-
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/src/DialogHelper.cpp b/src/DialogHelper.cpp
index e789fd0..79f3969 100644
--- a/src/DialogHelper.cpp
+++ b/src/DialogHelper.cpp
@@ -8,6 +8,12 @@ namespace YYCC::DialogHelper {
 
 #pragma region COM Guard
 
+	/**
+	 * @brief The guard for initialize COM environment.
+	 * @details This class will try initializing COM environment by calling CoInitialize when constructing,
+	 * and it also will try uninitializing COM environment when destructing.
+	 * If initialization failed, uninitialization will not be executed.
+	*/
 	class ComGuard {
 	public:
 		ComGuard() : m_HasInit(false) {
@@ -24,6 +30,14 @@ namespace YYCC::DialogHelper {
 		bool m_HasInit;
 	};
 
+	/**
+	 * @brief The instance of COM environment guard.
+	 * @details Dialog related function need COM environment,
+	 * so we need initializing COM environment when loading this module,
+	 * and uninitializing COM environment when we no longer use this module.
+	 * So we use a static instance in here.
+	 * And make it be const so no one can change it.
+	*/
 	static const ComGuard c_ComGuard;
 
 #pragma endregion
@@ -159,6 +173,13 @@ namespace YYCC::DialogHelper {
 		OpenFolder
 	};
 
+	/**
+	 * @brief Extract display name from given IShellItem*.
+	 * @param item[in] The pointer to IShellItem for extracting.
+	 * @param ret[out] Extracted display name container.
+	 * @return True if success, otherwise false.
+	 * @remarks This is an assist function of CommonFileDialog.
+	*/
 	bool ExtractDisplayName(IShellItem* item, std::string& ret) {
 		// fetch display name from IShellItem*
 		LPWSTR _name;
@@ -174,6 +195,15 @@ namespace YYCC::DialogHelper {
 		return true;
 	}
 
+	/**
+	 * @brief General file dialog.
+	 * @param params[in] User specified parameter controlling the behavior of this file dialog,
+	 * including title, file types and etc.
+	 * @param ret[out] The path to user selected files or folders.
+	 * For multiple selection, the count of items >= 1. For other scenario, the count of item is 1.
+	 * @return True if success, otherwise false (input parameters is wrong or user click "Cancel" in popup window).
+	 * @remarks This function is the real underlying function of all dialog functions.
+	*/
 	template<CommonFileDialogType EDialogType>
 	bool CommonFileDialog(const FileDialog& params, std::vector<std::string>& ret) {
 		// Reference: https://learn.microsoft.com/en-us/windows/win32/shell/common-file-dialog
diff --git a/src/DialogHelper.hpp b/src/DialogHelper.hpp
index 6255930..0f4cace 100644
--- a/src/DialogHelper.hpp
+++ b/src/DialogHelper.hpp
@@ -16,6 +16,9 @@ namespace YYCC::DialogHelper {
 
 #pragma region COM Pointer Management
 
+	/**
+	 * @brief C++ standard deleter for every COM interfaces inheriting IUnknown.
+	*/
 	class ComPtrDeleter {
 	public:
 		ComPtrDeleter() {}
@@ -32,6 +35,9 @@ namespace YYCC::DialogHelper {
 	using SmartIShellItemArray = std::unique_ptr<IShellItemArray, ComPtrDeleter>;
 	using SmartIShellFolder = std::unique_ptr<IShellFolder, ComPtrDeleter>;
 
+	/**
+	 * @brief C++ standard deleter for almost raw pointer used in COM which need to be free by CoTaskMemFree()
+	*/
 	class CoTaskMemDeleter {
 	public:
 		CoTaskMemDeleter() {}
@@ -112,6 +118,7 @@ namespace YYCC::DialogHelper {
 		 * @brief Generate Windows dialog system used data struct.
 		 * @param win_result[out] The class holding the generated filter data struct.
 		 * @return True if generation is success, otherwise false.
+		 * @remarks User should not call this function, this function is used in internal code.
 		*/
 		bool Generate(WinFileFilters& win_result) const;
 
@@ -156,6 +163,8 @@ namespace YYCC::DialogHelper {
 		/**
 		 * @brief The default selected file type in dialog
 		 * @remarks This is 1-based index according to Windows specification.
+		 * In other words, you should plus 1 for this index when generating this struct from
+		 * user oriented file dialog parameters.
 		*/
 		UINT m_WinDefaultFileTypeIndex;
 		bool m_HasTitle, m_HasInitFileName;
@@ -205,6 +214,9 @@ namespace YYCC::DialogHelper {
 				m_InitDirectory = init_dir;
 		}
 
+		/**
+		 * @brief Clear file dialog parameters for following re-use.
+		*/
 		void Clear() {
 			m_Owner = nullptr;
 			m_HasTitle = m_HasInitFileName = m_HasInitDirectory = false;
@@ -214,7 +226,13 @@ namespace YYCC::DialogHelper {
 			m_FileTypes.Clear();
 			m_DefaultFileTypeIndex = 0u;
 		}
-
+		
+		/**
+		 * @brief Generate Windows dialog system used data struct.
+		 * @param win_result[out] The class holding the generated filter data struct.
+		 * @return True if generation is success, otherwise false.
+		 * @remarks User should not call this function, this function is used in internal code.
+		*/
 		bool Generate(WinFileDialog& win_result) const;
 
 	protected: