From a1699f13db34bc2042ebe92967814e4a6760df68 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Fri, 5 Jul 2024 22:25:14 +0800 Subject: [PATCH] doc: update documentation - rename Constrain to Constraint in code and documentation. - remove massive annotation of encoding helper because the documentation is enough. - fix doxygen character shift warnings. --- doc/src/platform_checker.dox | 2 +- doc/src/win_import.dox | 6 ++--- src/ConfigManager.hpp | 30 ++++++++++++------------- src/EncodingHelper.hpp | 43 +++++------------------------------- testbench/main.cpp | 4 ++-- 5 files changed, 26 insertions(+), 59 deletions(-) diff --git a/doc/src/platform_checker.dox b/doc/src/platform_checker.dox index 1d0613e..b33f86b 100644 --- a/doc/src/platform_checker.dox +++ b/doc/src/platform_checker.dox @@ -30,6 +30,6 @@ blabla(); #endif \endcode -It's enough and simple that use \c #if to bracket the Windows specified code. +It's enough and simple that use \c \#if to bracket the Windows specified code. */ \ No newline at end of file diff --git a/doc/src/win_import.dox b/doc/src/win_import.dox index 17917b4..141667f 100644 --- a/doc/src/win_import.dox +++ b/doc/src/win_import.dox @@ -36,7 +36,7 @@ This guard can solve following issues: Programmer will not be affected by the automatical rename of \c GetObject, \c GetClassName and etc.
  • @@ -56,13 +56,13 @@ Because this guard operate some Windows macros as we introduced above. The headers depending on Windows may throw error if you put them outside of this pair. Please note WinImportPrefix.hpp and WinImportSuffix.hpp can be included multiple times. -Because they do not have the proprocessor command like #pragma once or etc to make sure they only can be included once. +Because they do not have the proprocessor command like \#pragma once or etc to make sure they only can be included once. That's by design. Because we actually may use this pair multiple times. The only thing you should pledge is that you must make sure they are presented by pair. This guard is Windows specific. It does nothing if you accidently use it in other platforms such as Linux, -because the headers use \c #if to check environment out and will do nothing in non-Windows environment. +because the headers use \c \#if to check environment out and will do nothing in non-Windows environment. However, we still highly recommend you use this pair with platform checker bracket like example does, if your program need to be run on multiple platforms. diff --git a/src/ConfigManager.hpp b/src/ConfigManager.hpp index 76925c2..5a1d40e 100644 --- a/src/ConfigManager.hpp +++ b/src/ConfigManager.hpp @@ -13,7 +13,7 @@ namespace YYCC::ConfigManager { template - struct Constrain { + struct Constraint { using CheckFct_t = std::function; //using CorrectFct_t = std::function<_Ty(const _Ty&)>; CheckFct_t m_CheckFct; @@ -24,13 +24,13 @@ namespace YYCC::ConfigManager { } }; - namespace ConstrainPresets { + namespace ConstraintPresets { template && !std::is_enum_v<_Ty> && !std::is_same_v<_Ty, bool>, int> = 0> - Constrain<_Ty> GetNumberRangeConstrain(_Ty min_value, _Ty max_value) { + Constraint<_Ty> GetNumberRangeConstraint(_Ty min_value, _Ty max_value) { if (min_value > max_value) - throw std::invalid_argument("invalid min max value for NumberRangeConstrain"); - return Constrain<_Ty> { + throw std::invalid_argument("invalid min max value for NumberRangeConstraint"); + return Constraint<_Ty> { [min_value, max_value](const _Ty& val) -> bool { return (val <= max_value) && (val >= min_value); } /*[min_value, max_value](const _Ty& val) -> _Ty { return std::clamp(val, min_value, max_value); }*/ }; @@ -96,14 +96,14 @@ namespace YYCC::ConfigManager { template || std::is_enum_v<_Ty>, int> = 0> class NumberSetting : public AbstractSetting { public: - NumberSetting(const yycc_char8_t* name, _Ty default_value, Constrain<_Ty> constrain = Constrain<_Ty> {}) : - AbstractSetting(name), m_Data(default_value), m_DefaultData(default_value), m_Constrain(constrain) {} + NumberSetting(const yycc_char8_t* name, _Ty default_value, Constraint<_Ty> constraint = Constraint<_Ty> {}) : + AbstractSetting(name), m_Data(default_value), m_DefaultData(default_value), m_Constraint(constraint) {} virtual ~NumberSetting() {} _Ty Get() const { return m_Data; } bool Set(_Ty new_data) { // validate data - if (m_Constrain.IsValid() && !m_Constrain.m_CheckFct(new_data)) + if (m_Constraint.IsValid() && !m_Constraint.m_CheckFct(new_data)) return false; // assign data m_Data = new_data; @@ -117,7 +117,7 @@ namespace YYCC::ConfigManager { return false; m_Data = *reinterpret_cast(GetDataPtr()); // check data - if (m_Constrain.IsValid() && !m_Constrain.m_CheckFct(m_Data)) + if (m_Constraint.IsValid() && !m_Constraint.m_CheckFct(m_Data)) return false; return true; } @@ -132,13 +132,13 @@ namespace YYCC::ConfigManager { } _Ty m_Data, m_DefaultData; - Constrain<_Ty> m_Constrain; + Constraint<_Ty> m_Constraint; }; class StringSetting : public AbstractSetting { public: - StringSetting(const yycc_char8_t* name, const yycc_char8_t* default_value, Constrain constrain = Constrain {}) : - AbstractSetting(name), m_Data(), m_DefaultData(), m_Constrain(constrain) { + StringSetting(const yycc_char8_t* name, const yycc_char8_t* default_value, Constraint constraint = Constraint {}) : + AbstractSetting(name), m_Data(), m_DefaultData(), m_Constraint(constraint) { if (default_value != nullptr) { m_Data = default_value; m_DefaultData = default_value; @@ -151,7 +151,7 @@ namespace YYCC::ConfigManager { // check data validation if (new_data == nullptr) return false; - if (m_Constrain.IsValid() && !m_Constrain.m_CheckFct(m_Data)) + if (m_Constraint.IsValid() && !m_Constraint.m_CheckFct(m_Data)) return false; // assign data m_Data = new_data; @@ -173,7 +173,7 @@ namespace YYCC::ConfigManager { string_length ); // check data - if (m_Constrain.IsValid() && !m_Constrain.m_CheckFct(m_Data)) + if (m_Constraint.IsValid() && !m_Constraint.m_CheckFct(m_Data)) return false; return true; } @@ -194,7 +194,7 @@ namespace YYCC::ConfigManager { } yycc_u8string m_Data, m_DefaultData; - Constrain m_Constrain; + Constraint m_Constraint; }; #pragma endregion diff --git a/src/EncodingHelper.hpp b/src/EncodingHelper.hpp index 8f28169..a18cd84 100644 --- a/src/EncodingHelper.hpp +++ b/src/EncodingHelper.hpp @@ -10,48 +10,15 @@ #endif /** - * @brief The namespace handling encoding issues. + * @brief The helper for all encoding aspects. * @details - * \par Windows Encoding Convertion - * This namespace provides the convertion between wchar_t, UTF8 and code-page-based string: - * The function name has following format: \c AAAToBBB. - * AAA is the source string and BBB is target string. - * AAA and BBB has following possible value: - * \li \c Char: Code-page-based string. Usually it will add a code page parameter for function to get the code page of this string. For code page, please see Microsoft document. - * \li \c UTF8: UTF8 string. - * \li \c Wchar: wchar_t string. - * \par - * For example: \c WcharToUTF8 will perform the convertion from wchar_t to UTF8, - * and \c CharToChar will perform the convertion between 2 code-page-based string and caller can specify individual code page for these 2 string. - * \par - * These functions are Windows specific and are unavailable on other platforms. - * Becasue Windows use wchar_t string as its function arguments for globalization, and this library use UTF8 everywhere. - * So it should have a bidirectional way to do convertion between wchar_t string and UTF8 string. - * - * \par UTF32, UTF16 and UTF8 Convertion - * This namespace also provide the convertion among UTF32, UTF16 and UTF8. - * These convertion functions are suit for all platforms, not Windows oriented. - * \par - * Due to implementation, this library assume all non-Windows system use UTF8 as their C locale. - * Otherwise these functions will produce wrong result. - * - * \par Function Parameters - * We provide these encoding convertion functions with following 2 types: - * \li Function returns \c bool and its parameter order source string pointer and a corresponding \c std::basic_string container for receiving result. - * \li Function returns corresponding \c std::basic_string result, and its parameter only order source string pointer. - * \par - * For these 2 declarations, both of them will not throw any exception and do not accept nullptr as source string. - * The only difference is that the way to indicate convertion error. - * \par - * First declaration will return false to indicate there is an error when doing convertion. Please note that the content of string container passing in may still be changed! - * Last declaration will return empty string to indicate error. Please note if you pass empty string in, they still will output empty string but it doesn't mean an error. - * So last declaration is used in the scenario that we don't care whether the convertion success did. For example, output something to console. - * + * For more infomations about how to use the functions provided by this namespace, + * please see \ref library_encoding and \ref encoding_helper. */ namespace YYCC::EncodingHelper { -#define _YYCC_U8(strl) u8 ## strl -#define YYCC_U8(strl) (reinterpret_cast(_YYCC_U8(strl))) +#define _YYCC_U8(strl) u8 ## strl ///< The assistant macro for YYCC_U8. +#define YYCC_U8(strl) (reinterpret_cast(_YYCC_U8(strl))) ///< The macro for creating UTF8 string literal. See \ref library_encoding. const yycc_char8_t* ToUTF8(const char* src); yycc_char8_t* ToUTF8(char* src); diff --git a/testbench/main.cpp b/testbench/main.cpp index 9f9daa5..2bcf920 100644 --- a/testbench/main.cpp +++ b/testbench/main.cpp @@ -401,7 +401,7 @@ namespace YYCCTestbench { m_FloatSetting(YYCC_U8("float-setting"), 0.0f), m_StringSetting(YYCC_U8("string-setting"), YYCC_U8("")), m_BoolSetting(YYCC_U8("bool-setting"), false), - m_ClampedFloatSetting(YYCC_U8("clamped-float-setting"), 0.0f, YYCC::ConfigManager::ConstrainPresets::GetNumberRangeConstrain(-1.0f, 1.0f)), + m_ClampedFloatSetting(YYCC_U8("clamped-float-setting"), 0.0f, YYCC::ConfigManager::ConstraintPresets::GetNumberRangeConstraint(-1.0f, 1.0f)), m_EnumSetting(YYCC_U8("enum-setting"), TestEnum::Test1), m_CoreManager(YYCC_U8("test.cfg"), UINT64_C(0), { &m_IntSetting, &m_FloatSetting, &m_StringSetting, &m_BoolSetting, &m_ClampedFloatSetting, &m_EnumSetting @@ -436,7 +436,7 @@ namespace YYCCTestbench { // init cfg manager TestConfigManager test; - // test constrain works + // test constraint works Assert(!test.m_ClampedFloatSetting.Set(2.0f), YYCC_U8("YYCC::ConfigManager::Constraint")); Assert(test.m_ClampedFloatSetting.Get() == 0.0f, YYCC_U8("YYCC::ConfigManager::Constraint"));