From b912be082c7d71f9f2776483c97f0bc91f648f4f Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Mon, 15 Jul 2024 13:47:14 +0800 Subject: [PATCH] doc: add documentation for COMHelper --- doc/src/com_helper.dox | 33 +++++++++++++++++++++++++++++++++ doc/src/index.dox | 2 ++ doc/src/string_helper.dox | 6 +++--- src/COMHelper.hpp | 19 ------------------- 4 files changed, 38 insertions(+), 22 deletions(-) create mode 100644 doc/src/com_helper.dox diff --git a/doc/src/com_helper.dox b/doc/src/com_helper.dox new file mode 100644 index 0000000..cd9ca75 --- /dev/null +++ b/doc/src/com_helper.dox @@ -0,0 +1,33 @@ +/** + +\page com_helper COM Helper + +This namespace is Windows specific. +It will be invisible on other platforms. + +This namespace is used by internal functions as intended. +They should not be used outside of this library. +But if you compel to use them, it is also okey. + +\section com_helper__memory_safe_ptr Memory Safe Pointer Types + +This namespace also provided various memory-safe types for interacting with COM functions. +Although Microsoft also has similar smart pointer called \c CComPtr. +But this library is eager to hide all Microsoft-related functions calling. +Using \c CComPtr is not corresponding with the philosophy of this library. +So these standard library based smart pointer types were created. + +\section com_helper__com_guard COM Guard + +This namespace contain a COM Guard which make sure COM was initialized in current module when loading current module. +It is essential because all calling to COM functions should be under the premise that COM has been initialized. +This guard also will uninitialize COM when unloading this module. + +There is only an exposed function called YYCC::COMHelper::IsInitialized for user calling. +This function will check whether COM environment is initialized. +If you want YYCC automatically initialize COM environment for you, +you must call this function in your program at least one time. +Otherwise COM Guard code may be unavailable, +because compiler may think they are not essential code and drop them. + +*/ \ No newline at end of file diff --git a/doc/src/index.dox b/doc/src/index.dox index b4a2820..67895cc 100644 --- a/doc/src/index.dox +++ b/doc/src/index.dox @@ -54,6 +54,8 @@ \li \subpage win_import + \li \subpage com_helper + \li \subpage dialog_helper \li \subpage win_fct_helper diff --git a/doc/src/string_helper.dox b/doc/src/string_helper.dox index e8004b2..1aca538 100644 --- a/doc/src/string_helper.dox +++ b/doc/src/string_helper.dox @@ -28,16 +28,16 @@ std::vector Split(const yycc_u8string_view&, const yycc_char8_t*) std::vector SplitView(const yycc_u8string_view&, const yycc_char8_t*); \endcode -All these overloads take a string view as the first argument for the string need to be split. +All these overloads take a string view as the first argument representing the string need to be split. The second argument is a raw string pointer representing the decilmer for splitting. The only difference between these 2 split function are overt according to their names. The first split function will return a list of copied string as its split result. The second split function will return a list of string view as its split result, and it will keep valid as long as the life time of your given string view argument. -It also means that the last type will cost less memory if you don't need the copy of original string. +It also means that the last overload will cost less memory if you don't need the copy of original string. If the source string (the string need to be split) is empty, or the decilmer is \c nullptr or empty, the result will only has 1 item and this item is source string itself. -There is no way that this method return an empty list, except the code is buggy. +There is no way that these methods return an empty list, except the code is buggy. */ diff --git a/src/COMHelper.hpp b/src/COMHelper.hpp index 338109c..aded88a 100644 --- a/src/COMHelper.hpp +++ b/src/COMHelper.hpp @@ -9,25 +9,6 @@ #include #include "WinImportSuffix.hpp" -/** - * @brief COM fucntions related namespace. - * @details - * This namespace is Windows specific and is unavailable on other platforms. - * - * This namespace contain a COM Guard which make sure COM was initialized in current module when loading current module. - * It is essential because all calling to COM functions should be under the premise that COM has been initialized. - * This guard also will uninitialize COM when unloading this module. - * - * This namespace also provided various memory-safe types for interacting with COM functions. - * Although Microsoft also has similar smart pointer called \c CComPtr. - * But this library is eager to hide all Microsoft-related functions calling. - * Using \c CComPtr is not corresponding with the philosophy of this library. - * So these std-based smart pointer type were created. - * - * This namespace is used by internal functions as intended. - * They should not be used outside of this library. - * But if you compel to use them, it is also okey. -*/ namespace YYCC::COMHelper { /**