refactor: refactor doc layout

doc/src/constraints.dox

@@ -1,49 +0,0 @@
-namespace YYCC::Constraints {
-/**
-
-\page constraints Constraints
-
-YYCC::Constraints namespace provide Constraint struct declaration
-and various common constraint generator function.
-
-This namespace is specifically used by YYCC::ConfigManager and YYCC::ArgParser namespaces.
-See \ref config_manager chapter and \ref arg_parser chapter for how to utlize this namespace.
-
-\section constraints__prototype Prototype
-
-Constraint instruct library how check whether given value is in range,
-and how to clamp it if it is invalid.
-For example, you can use constraint to limit a number in given minimum maximum value,
-or limit a string in specific format by using regex and etc.
-
-Constraint is a template struct.
-The argument of template is the underlying data type which need to be checked.
-The struct with different template argument is not compatible.
-
-Currently, this struct only contain 1 function pointer,
-which is used for detecting whether given value is in range / valid.
-
-\subsection constraints__presets Constraint Presets
-
-YYCC::Constraints provides some constraint presets which are commonly used.
-All functions inside this namespace will return a Constraint instance,
-and you can directly use it.
-
-There is a list of all provided functions:
-
-\li GetMinMaxRangeConstraint(): Limit the number value in given minimum maximum value range (inclusive).
-\li GetEnumEnumerationConstraint(): Limit the enum value by given all possible value set.
-\li GetStringEnumerationConstraint(): Limit the string by given all possible value set.
-
-\subsection config_manager__constraint__custom Custom Constraint
-
-For creating your personal constraint,
-you need to create Constraint instance manually.
-You can browse all existing constraint preset functions code for know how to write it.
-
-The things you need to do is simple.
-First, you need decide the template argument of Constraint.
-Second, you need assign class member of Constraint by C++ lambda syntax.
-
-*/
-}

doc/src/index.dox

@@ -31,15 +31,17 @@
 
     \li \subpage premise_and_principle
 
-    \li \subpage library_macros
+    <B>STL Enhancements</B>
+
+    \li \subpage macro
+
+    \li \subpage string_reinterpret
 
     <!--
-    \li \subpage library_encoding
+    \li \subpage string_helper
 
     \li \subpage encoding_helper
 
-    \li \subpage string_helper
-
     \li \subpage parser_helper
 
     \li \subpage console_helper
@@ -51,8 +53,6 @@
     \li \subpage enum_helper
     -->
 
-    <B>Advanced Features</B>
-
     <!--
     \li \subpage constraints
 
@@ -64,6 +64,8 @@
   </TD>
   <TD ALIGN="LEFT" VALIGN="TOP">
 
+    <B>Advanced Features</B>
+
     <B>Windows Specific Features</B>
 
     <!--

doc/src/macro.dox

@@ -1,12 +1,12 @@
 namespace yycc::macro {
 /**
 
-\page library_macros Library Macros
+\page macro Library Macros
 
 In this page we will introduce the macros defined by this library
 which can not be grouped in other topic.
 
-\section library_macros__batch_class_copy_move Library Version and Version Comparison
+\section macro__version_cmp Library Version and Version Comparison
 
 Version is a important things in modern software development, especially for a library.
 In YYCC, we use Semantic Versioning as our version standard.
@@ -48,7 +48,7 @@ There is a example about checking whether YYCC library version is exactly what w
 #endif
 \endcode
 
-\section library_macros__class_copy_move Class Copy / Move Functions
+\section macro__copy_move Class Copy / Move Functions
 
 YYCC provides several macros to manage copy and move constructors and assignment operators for classes.
 These include macros to delete, default, declare, and implement copy and move operations.
@@ -139,7 +139,7 @@ YYCC_IMPL_MOVE_OPER(Foo, rhs)
 }
 \endcode
 
-\section library_macros__platform_checker OS Detector
+\section macro__platform_checker OS Detector
 
 In many cross platform applications, 
 programmer usually write code adapted to different platforms in one source file 
@@ -147,7 +147,7 @@ and enable them respectively by macros representing the target platform.
 As a cross platform library,
 YYCC also has this feature and you can utilize it if you don't have other ways to so the same things.
 
-\subsection library_macros__platform_checker__macro Macro
+\subsection macro__platform_checker__macro Macro
 
 YYCC always define <B>one of following macros</B> to indicate the system of target platform.
 
@@ -165,7 +165,7 @@ blabla();
 #endif
 \endcode
 
-\subsection library_macros__platform_checker__constexpr_function Constexpr Function
+\subsection macro__platform_checker__constexpr_function Constexpr Function
 
 Additionally, YYCC also provides a bunch of constexpr functions to check whether the target platform is what we want.
 More precisely, os::get_os() function returns an enum value os::OsKind indicating the target platform.
@@ -179,11 +179,11 @@ if constexpr (os::get_os() == os::OsKind::Windows) {
 }
 \endcode
 
-\section library_macros__compiler_detector Compiler Detector
+\section macro__compiler_detector Compiler Detector
 
 YYCC provides macros and constexpr functions to detect the compiler being used for compilation.
 
-\subsection library_macros__compiler_detector__macro Macro
+\subsection macro__compiler_detector__macro Macro
 
 YYCC defines <B>one of following macros</B> to indicate which compiler is being used.
 
@@ -200,7 +200,7 @@ blabla();
 #endif
 \endcode
 
-\subsection library_macros__compiler_detector__constexpr_function Constexpr Function
+\subsection macro__compiler_detector__constexpr_function Constexpr Function
 
 YYCC also provides a constexpr function to check which compiler is being used at compile time.
 More precisely, compiler::get_compiler() function returns an enum value compiler::CompilerKind indicating the compiler being used.
@@ -214,11 +214,11 @@ if constexpr (compiler::get_compiler() == compiler::CompilerKind::Msvc) {
 }
 \endcode
 
-\section library_macros__endian_detector Endian Detector
+\section macro__endian_detector Endian Detector
 
 YYCC provides macros and constexpr functions to detect the endianness of the target platform.
 
-\subsection library_macros__endian_detector__macro Macro
+\subsection macro__endian_detector__macro Macro
 
 YYCC always defines <B>one of following macros</B> to indicate the endianness of the target platform.
 
@@ -234,7 +234,7 @@ blabla();
 #endif
 \endcode
 
-\subsection library_macros__endian_detector__constexpr_function Constexpr Function
+\subsection macro__endian_detector__constexpr_function Constexpr Function
 
 YYCC also provides a constexpr function to check the endianness of the target platform.
 More precisely, endian::get_endian() function returns an enum value endian::EndianKind indicating the endianness.
@@ -248,11 +248,11 @@ if constexpr (endian::get_endian() == endian::EndianKind::Little) {
 }
 \endcode
 
-\section library_macros__stl_detector STL Detector
+\section macro__stl_detector STL Detector
 
 YYCC provides macros to detect which Standard Template Library (STL) implementation is being used.
 
-\subsection library_macros__stl_detector__macro Macro
+\subsection macro__stl_detector__macro Macro
 
 YYCC defines <B>one of following macros</B> to indicate which STL implementation is being used.
 
@@ -269,7 +269,7 @@ blabla();
 #endif
 \endcode
 
-\subsection library_macros__stl_detector__constexpr_function Constexpr Function
+\subsection macro__stl_detector__constexpr_function Constexpr Function
 
 YYCC also provides a constexpr function to check which STL implementation is being used at compile time.
 More precisely, stl::get_stl() function returns an enum value stl::StlKind indicating the STL implementation.
@@ -283,11 +283,11 @@ if constexpr (stl::get_stl() == stl::StlKind::MsStl) {
 }
 \endcode
 
-\section library_macros__ptr_size_detector Pointer Size Detector
+\section macro__ptr_size_detector Pointer Size Detector
 
 YYCC provides macros and constexpr functions to detect the pointer size of the target platform.
 
-\subsection library_macros__ptr_size_detector__macro Macro
+\subsection macro__ptr_size_detector__macro Macro
 
 YYCC always define <B>one of following macros</B> to indicate the pointer size of target platform.
 
@@ -303,7 +303,7 @@ blabla();
 #endif
 \endcode
 
-\subsection library_macros__ptr_size_detector__constexpr_function Constexpr Function
+\subsection macro__ptr_size_detector__constexpr_function Constexpr Function
 
 YYCC also provides a constexpr function to check the pointer size of the target platform.
 More precisely, ptr_size::get_ptr_size() function returns an enum value ptr_size::PtrSizeKind indicating the pointer size.

doc/src/premise_and_principle.dox

@@ -24,7 +24,13 @@ We brutally make a premise that other operating systems are POSIX-compatible and
 \section premise_and_principle__string_encoding String Encoding
 
 Before using this library, you should know the encoding strategy of this library first.
-In short words, this library use UTF8 encoding everywhere except some special cases list following (not all).
+After upgrade the whole project into C++23, \c char8_t is the only valid UTF8 char type.
+\c std::u8string and \c std::u8string_view are the only valid UTF8 string container and viewer.
+And, \c u8 string literal prefix is the only way to create UTF8 string literal.
+In brief words, this library use UTF8 encoding everywhere.
+
+However, there are some special cases that use ordinary string instead of UTF8 string list following 
+(also, not all cases are covered).
 
 \li Traditional format function in yycc::string::op.
 Traditional format function provide some overloads for ordinary string formatting.

doc/src/string/string_reinterpret.dox

@@ -1,66 +1,22 @@
-namespace YYCC {
+namespace yycc {
 /**
 
-\page library_encoding Library Encoding
+\page string_reinterpret String Reinterpret
 
-Before using this library, you should know the encoding strategy of this library first.
-In short words, this library use UTF8 encoding everywhere except some special cases,
-for example, function explicitly order the encoding of input parameters.
+Now, you have know that we use UTF8 string everywhere in this project
+as we introduced in \ref premise_and_principle__string_encoding.
+Now it's time to know how to fetch UTF8 string from user or anywhere else.
 
-In following content of this article, you will know the details about how we use UTF8 in this library.
 
-\section library_encoding__utf8_type UTF8 Type
+\section string_reinterpret__utf8_type UTF8 Type
 
-YYCC uses custom UTF8 char type, string container and string view all over the library, from parameters to return value.
-Following content will introduce how we define them.
+After upgrade the whole project into C++23, \c char8_t is the only valid UTF8 char type.
+And \c std::u8string and \c std::u8string_view are the only valid UTF8 string container and viewer.
+Additionally, \c u8 string literal prefix is the only way to create UTF8 string literal.
 
-\subsection library_encoding__utf8_type__char_type Char Type
+All in all, please use this library provided string functions with UTF8 format.
 
-YYCC library has its own UTF8 char type, \c yycc_char8_t.
-This is how we define it:
-
-\code
-#if defined(__cpp_char8_t)
-using yycc_char8_t = char8_t;
-#else
-using yycc_char8_t = unsigned char;
-#endif
-\endcode
-
-If your environment (higher or equal to C++ 20) supports \c char8_t provided by standard library, \c yycc_char8_t is just an alias to \c char8_t,
-otherwise (lower than C++ 20, e.g. C++ 17), \c yycc_char8_t will be defined as \c unsigned \c char like C++ 20 does (this can be seen as a polyfill).
-
-This means that if you already have used \c char8_t provided by standard library,
-you do not need to do any extra modification before using this library.
-Because all types are compatible.
-
-\subsection library_encoding__utf8_type__container_type String Container and View
-
-We define string container and string view like this:
-
-\code
-using yycc_u8string = std::basic_string<yycc_char8_t>;
-using yycc_u8string_view = std::basic_string_view<yycc_char8_t>;
-\endcode
-
-The real code written in library may be slightly different with this but they have same meanings.
-
-In \c char8_t environment, they are just the alias to \c std::u8string and \c std::u8string_view respectively.
-So if you have already used them, no need to any modification for your code before using this library.
-
-\subsection library_encoding__utf8_type__why Why?
-
-You may curious why I create a new UTF8 char type, rather than using standard library UTF8 char type directly. There are 2 reasons.
-
-First, It was too late that I notice I can use standard library UTF8 char type.
-My UTF8 char type has been used in library everywhere and its tough to fully replace them into standard library UTF8 char type.
-
-Second, UTF8 related content of standard library is \e volatile.
-I notice standard library change UTF8 related functions frequently and its API are not stable.
-For example, standard library brings \c std::codecvt_utf8 in C++ 11, deprecate it in C++ 17 and even remove it in C++ 26.
-That's unacceptable! So I create my own UTF8 type to avoid the scenario that standard library remove \c char8_t in future.
-
-\section library_encoding__concept Concepts
+\section string_reinterpret__concept Concepts
 
 In following content, you may be face with 2 words: ordinary string and UTF8 string.
 
@@ -77,12 +33,12 @@ Its encoding depends on compiler and environment.
 For more infomation, please browse CppReference:
 https://en.cppreference.com/w/cpp/language/string_literal
 
-\section library_encoding__utf8_literal UTF8 Literal
+\section string_reinterpret__utf8_literal UTF8 Literal
 
 String literal is a C++ concept.
 If you are not familar with it, please browse related article first, such as CppReference.
 
-\subsection library_encoding__utf8_literal__single Single Literal
+\subsection string_reinterpret__utf8_literal__single Single Literal
 
 In short words, YYCC allow you declare an UTF8 literal like this:
 
@@ -97,7 +53,7 @@ This macro will do this automatically.
 In detail, this macro do a \c reinterpret_cast to change the type of given argument to \c const \c yycc_char8_t* forcely.
 This ensure that declared UTF8 literal is compatible with YYCC UTF8 types.
 
-\subsection library_encoding__utf8_literal__char Single Char
+\subsection string_reinterpret__utf8_literal__char Single Char
 
 Same as UTF8 literal, YYCC allow you cast normal \c char into \c yycc_char8_t as following code:
 
@@ -115,7 +71,7 @@ For example, following code is \b invalid:
 YYCC_U8_CHAR('文') // INVALID!
 \endcode
 
-\subsection library_encoding__utf8_literal__concatenation Literal Concatenation
+\subsection string_reinterpret__utf8_literal__concatenation Literal Concatenation
 
 YYCC_U8 macro also works for string literal concatenation:
 
@@ -129,7 +85,7 @@ At the same time, YYCC_U8 macro will automatically add \c u8 prefix for the firs
 So the whole string will be UTF8 literal.
 It also order you should \b not add any prefix for other components of this string literal concatenation.
 
-\subsection library_encoding__utf8_literal__why Why?
+\subsection string_reinterpret__utf8_literal__why Why?
 
 You may know that C++ standard allows programmer declare an UTF8 literal explicitly by writing code like this:
 
@@ -144,7 +100,7 @@ This behavior cause that you can not assign this UTF8 literal to \c yycc_u8strin
 because their types are different.
 Thereas you can not use the functions provided by this library because they are all use YYCC defined UTF8 char type.
 
-\section library_encoding__utf8_pointer UTF8 String Pointer
+\section string_reinterpret__utf8_pointer UTF8 String Pointer
 
 String pointer means the raw pointer pointing to a string, such as \c const \c char*, \c char*, \c char32_t* and etc.
 
@@ -174,7 +130,7 @@ char* mutable_converted = YYCC::EncodingHelper::ToOrdinary(mutable_yycc_utf8);
 
 Same as YYCC::EncodingHelper::ToUTF8, YYCC::EncodingHelper::ToOrdinary also has 2 overloads to handle constant and mutable string pointer.
 
-\section library_encoding__utf8_container UTF8 String Container
+\section string_reinterpret__utf8_container UTF8 String Container
 
 String container usually means the standard library string container, such as \c std::string, \c std::wstring, \c std::u32string and etc.
 
@@ -212,7 +168,7 @@ Same as UTF8 string pointer, we also have YYCC::EncodingHelper::ToOrdinary and Y
 Try to do your own research and figure out how to use them.
 It's pretty easy.
 
-\section library_encoding__windows Warnings to Windows Programmer
+\section string_reinterpret__windows Warnings to Windows Programmer
 
 Due to the legacy of MSVC, the encoding of \c char* may not be UTF8 in most cases.
 If you run the convertion code introduced in this article with the string which is not encoded with UTF8, it may cause undefined behavior.