From 19023cb94907b036412f0864fa0e1b3f6f6aa6cb Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Tue, 30 Jul 2024 10:35:41 +0800 Subject: [PATCH] doc: add callback documentation in ExceptionHelper. - add callback documentation in ExceptionHelper. - fix other misc documentation issue. --- doc/src/arg_parser.dox | 8 ++++++++ doc/src/encoding_helper.dox | 2 +- doc/src/exception_helper.dox | 20 +++++++++++++++++++- doc/src/index.dox | 2 ++ src/ExceptionHelper.cpp | 2 ++ src/YYCCInternal.hpp | 6 +++--- 6 files changed, 35 insertions(+), 5 deletions(-) create mode 100644 doc/src/arg_parser.dox diff --git a/doc/src/arg_parser.dox b/doc/src/arg_parser.dox new file mode 100644 index 0000000..aea9deb --- /dev/null +++ b/doc/src/arg_parser.dox @@ -0,0 +1,8 @@ +/** + +\page arg_parser Universal Argument Parser + + + + +*/ \ No newline at end of file diff --git a/doc/src/encoding_helper.dox b/doc/src/encoding_helper.dox index 90d27c3..e232e10 100644 --- a/doc/src/encoding_helper.dox +++ b/doc/src/encoding_helper.dox @@ -106,7 +106,7 @@ So please note the type of result is decided by convertion function itself, not According to the way providing source string, these 4 overload also can be divided into 2 types. The first type take a reference to constant \c std::wstring_view. -The second type take a pointer to constant wchar_t. +The second type take a pointer to constant \c wchar_t. For first type, it will take the whole string for convertion, including \b embedded NUL terminal. Please note we use string view as argument. diff --git a/doc/src/exception_helper.dox b/doc/src/exception_helper.dox index 2b00c50..931fd47 100644 --- a/doc/src/exception_helper.dox +++ b/doc/src/exception_helper.dox @@ -18,11 +18,21 @@ It will be invisible on other platforms. \subsection exception_helper__usage__code Register Code -In most scenarios, programmer only need call YYCC::ExceptionHelper::Register() when program started or module loaded. +In most scenarios, programmer only need call YYCC::ExceptionHelper::Register when program started or module loaded. And call YYCC::ExceptionHelper::Unregister when program exited or module unloaded. All details are hidden by these 2 feature. Programmer do not need worried about the implementation of unhandled exception handler. +Optionally, you can provide a function pointer during calling YYCC::ExceptionHelper::Register as a callback. +The prototype of this function pointer is YYCC::ExceptionHelper::ExceptionCallback. +This callback will be called if any unhandled exception happened. +It provides 2 pathes to log file and core dump file respectively. +So that you can use an explicit way, e.g. \c MessageBox, to tell user exception happened and where are the log files, +especially in GUI application because the default output stream, \c stderr, is invisible in GUI application. + +However, please note the pathes provided by callback may be empty. +In this case, it means that handler fail to create corresponding log files. + \subsection exception_helper__usage__location Location When unhandled exception occurs, @@ -84,4 +94,12 @@ YYCC::ExceptionHelper has internal mechanism to prevent this bad case. If this really happened, the handler will quit silent and will not cause any issue. Programmer don't need to worry about this. +\subsection exception_helper__notes__user_callback The Timing of User Callback + +The timing of calling user callback is the tail of unhandled exception handler. +It means that all log and coredump have been written if possible before calling callback. +Because user callback may still raise exception. +We want all essential log files has been written before calling it, +so that at least we can visit them on disk or console. + */ diff --git a/doc/src/index.dox b/doc/src/index.dox index 65276e7..797db94 100644 --- a/doc/src/index.dox +++ b/doc/src/index.dox @@ -49,6 +49,8 @@ \li \subpage config_manager + \li \subpage arg_parser + diff --git a/src/ExceptionHelper.cpp b/src/ExceptionHelper.cpp index e3e303f..f02e9b8 100644 --- a/src/ExceptionHelper.cpp +++ b/src/ExceptionHelper.cpp @@ -78,6 +78,8 @@ namespace YYCC::ExceptionHelper { if (!m_IsRegistered) return; // unregister handler + // reset user callback + m_UserCallback = nullptr; // restore old handler SetUnhandledExceptionFilter(m_PrevProcHandler); m_PrevProcHandler = nullptr; diff --git a/src/YYCCInternal.hpp b/src/YYCCInternal.hpp index 0838b43..7614b49 100644 --- a/src/YYCCInternal.hpp +++ b/src/YYCCInternal.hpp @@ -46,21 +46,21 @@ namespace YYCC { #endif } /** - \typedef yycc_char8_t + \typedef YYCC::yycc_char8_t \brief YYCC UTF8 char type. \details This char type is an alias to \c std::char8_t if your current C++ standard support it. Otherwise it is defined as unsigned char as C++ 20 stdandard does. */ /** - \typedef yycc_u8string + \typedef YYCC::yycc_u8string \brief YYCC UTF8 string container type. \details This type is defined as \c std::basic_string. It is equal to \c std::u8string if your current C++ standard support it. */ /** - \typedef yycc_u8string_view + \typedef YYCC::yycc_u8string_view \brief YYCC UTF8 string view type. \details This type is defined as \c std::basic_string_view.