From c708e1e672b98a548d6d2030c073e4644de9e782 Mon Sep 17 00:00:00 2001
From: yyc12345 <yyc12321@outlook.com>
Date: Tue, 30 Dec 2025 16:15:34 +0800
Subject: [PATCH] doc: write doc for parse&stringify and windows import guard

---
 doc/src/index.dox                             |  8 +-
 doc/src/num/parser.dox                        | 70 +++++++++++++++
 doc/src/num/parser_helper.dox                 | 88 -------------------
 .../{win_import.dox => import_guard.dox}      | 20 +++--
 4 files changed, 85 insertions(+), 101 deletions(-)
 create mode 100644 doc/src/num/parser.dox
 delete mode 100644 doc/src/num/parser_helper.dox
 rename doc/src/windows/{win_import.dox => import_guard.dox} (80%)

diff --git a/doc/src/index.dox b/doc/src/index.dox
index 961723e..6cb5488 100644
--- a/doc/src/index.dox
+++ b/doc/src/index.dox
@@ -41,13 +41,13 @@
 
     \li \subpage string__op
 
+    \li \subpage num__parser
+
     \li \subpage patch
 
     <!--
     \li \subpage encoding_helper
 
-    \li \subpage parser_helper
-
     \li \subpage console_helper
 
     -->
@@ -67,9 +67,9 @@
 
     <B>Windows Specific Features</B>
 
-    <!--
-    \li \subpage win_import
+    \li \subpage windows__import_guard
 
+    <!--
     \li \subpage com_helper
 
     \li \subpage dialog_helper
diff --git a/doc/src/num/parser.dox b/doc/src/num/parser.dox
new file mode 100644
index 0000000..d6addbe
--- /dev/null
+++ b/doc/src/num/parser.dox
@@ -0,0 +1,70 @@
+namespace yycc::num::parse {
+/**
+
+\page num__parser Numeric Parser
+
+Namespace yycc::num::parse is served for the convertion from string to number.
+
+\section num__parser__supported_types Supported Types
+
+Functions located in this namespace support the convertion from string to following types:
+
+\li Integral types (except \c bool): \c int, \c uint32_t, \c char and etc.
+\li Floating point types: \c float, \c double and etc.
+\li \c bool
+
+Please note in C++, \c bool is integral type but we list it individually because parser will treat it specially.
+For \c bool type, parser will try doing convertion between it and \c "true" \c "false" string.
+(\b case-insensitive. It means that \c "true", \c "True" and \c "TRUE", all of them can be converted into \c true.)
+
+\section num__parser__usage Usage
+
+This namespace provide a uniform parser function #parse with various overloads.
+All of them accept an UTF8 string view at first argument,
+and following argument is different required by different overloads which may change parser behavior.
+For example, for floating point type, this function allows caller to specify extra argument providing the format of given number string (\c std::chars_format).
+or for integral type, this function allows caller to specify extra argument providing the base of given number string.
+The return value is a result type, containing converted value or error occurs.
+There are some examples:
+
+\code
+auto rv = parse::parse<uint32_t>(u8"123");
+assert(rv.has_value());
+auto converted = rv.value();
+\endcode
+
+\section num__parser__stringify Stringify
+
+Namespace yycc::num::stringify provide the opposite function of namespace yycc::num::parse.
+They convert given number into their string representation.
+There is an example:
+
+\code
+auto showcase = stringify::stringify<uint32_t>(UINT32_C(114));
+\endcode
+
+Same as parse::parse, stringify::stringify also has same overloads and different second arguments.
+For floating point type, this function allows caller to specify extra arguments
+which provides the format (\c std::chars_format) and precision when getting string representation.
+For integral type, this function allows caller to specify extra argument
+providing the base of number when getting string representation.
+However, the result value of stringify::stringify is just the result, not a result type.
+Because it is mostly impossible to occur error in stringify::stringify.
+
+\section num__parser__notes Notes
+
+All functions located in yycc::num::parse and yycc::num::stringify namespace are implementated by standard library functions.
+These functions just make a good wrapper for complex standard library functions.
+And give you a experience like Rust \c parse functions.
+
+Basically, all functions located in this helper have possibility to throw exception.
+But this possibility are more close to the possibility that \c new statement throw \c std::bad_alloc.
+So in most cases you can assume these functions will not throw any exception.
+
+All functions are template functions.
+The argument of template is the type these functions need to be processed.
+Although C++ have \e smart template type deduction, 
+it would be better to specify template argument manually to explicitly specify your desired type.
+
+*/
+}
\ No newline at end of file
diff --git a/doc/src/num/parser_helper.dox b/doc/src/num/parser_helper.dox
deleted file mode 100644
index 44669c7..0000000
--- a/doc/src/num/parser_helper.dox
+++ /dev/null
@@ -1,88 +0,0 @@
-namespace YYCC::ParserHelper {
-/**
-
-\page parser_helper Parser Helper
-
-This helper is served for the convertion between number and string.
-
-\section parser_helper_supported_types Supported Types
-
-Functions located in this helper support the convertion between string and following types:
-
-\li Integral types (except \c bool): \c int, \c uint32_t, \c char and etc.
-\li Floating point types: \c float, \c double and etc.
-\li \c bool
-
-Please note in C++, \c bool is integral type but we list it individually because parser will treat it specially.
-For \c bool type, parser will try doing convertion between it and \c "true" \c "false" string.
-(\b case-insensitive. It means that \c true can be converted from \c "true", \c "True" or \c "TRUE".)
-
-\section parser_helper__try_parse Try Parse
-
-#TryParse will try to parse string into caller specified type.
-All of them accept an UTF8 string view at first argument,
-require that you provide a container receiving converted result in the second argument,
-and return a bool value to indicate whether the convertion is successful.
-There are some examples:
-
-\code
-uint32_t val;
-YYCC::ParserHelper::TryParse<uint32_t>(YYCC_U8("123"), val);
-YYCC::ParserHelper::TryParse<uint32_t>(YYCC_U8("7fff"), val, 16);
-\endcode
-
-For floating point type, this function allows caller to specify extra argument providing the format of given number string (\c std::chars_format).
-For integral type, this function allows caller to specify extra argument providing the base of given number string.
-
-\section parser_helper__parse Parse
-
-#Parse is similar to #TryParse.
-But it will not return bool value to indicate success and doesn't have the argument receiving result.
-It only accepts an UTF8 string view as the only one argument, and return result directly.
-If the convertion failed, the return value is \b undefined (but usually is the default value of given type).
-There is an example:
-
-\code
-uint32_t val = YYCC::ParserHelper::Parse<uint32_t>(YYCC_U8("123"));
-\endcode
-
-For integral and floating point value, 
-it has same extra argument with #TryParse to provide more number infomation.
-
-Using this function is dangerous if the validation of your input is important.
-In this case, please use #TryParse instead.
-
-\section parser_helper__to_string To String
-
-#ToString basically is the reversed operation of #Parse.
-It gets the string representation of given type.
-The only argument of these functions is the type which need to be converted to its string representation.
-And they will return yycc_u8string as result.
-There is an example:
-
-\code
-auto result = YYCC::ParserHelper::ToString<uint32_t>(UINT32_C(114));
-\endcode
-
-For floating point type, this function allows caller to specify extra arguments
-which provides the format (\c std::chars_format) and precision when getting string representation.
-For integral type, this function allows caller to specify extra argument
-providing the base of number when getting string representation.
-
-\section parser_helper__notes Notes
-
-All functions within this helper are implementated by standard library functions.
-These functions just make a good wrapper for complex standard library functions.
-And give you a experience like C\# parser functions.
-
-Basically, all functions located in this helper have possibility to throw exception.
-But this possibility are more close to the possibility that \c new statement throw \c std::bad_alloc.
-So in most cases you can assume these functions will not throw any exception.
-
-All functions are template functions.
-The argument of template is the type these functions need to be processed.
-Although C++ have \e smart template type deduction, 
-it would be better to specify template argument manually to explicitly specify your desired type.
-
-*/
-}
\ No newline at end of file
diff --git a/doc/src/windows/win_import.dox b/doc/src/windows/import_guard.dox
similarity index 80%
rename from doc/src/windows/win_import.dox
rename to doc/src/windows/import_guard.dox
index 7269a12..62825f0 100644
--- a/doc/src/windows/win_import.dox
+++ b/doc/src/windows/import_guard.dox
@@ -1,25 +1,27 @@
-namespace YYCC {
+namespace yycc::windows {
 /**
 
-\page win_import Windows Import Guard
+\page windows__import_guard Windows Import Guard
 
 Windows is shitty for the programmer who is familiar with UNIX programming.
 Due to legacy reason, Windows defines various things which are not compatible with UNIX or standard C++ programming.
 
-\section win_import__usage Usage
+\section windows__import_guard__usage Usage
 
 YYCC has a way to solve the issue introduced above.
 
 \code
+#include <yycc/macro/os_detector.hpp>
+
 #if defined(YYCC_OS_WINDOWS)
-#include <WinImportPrefix.hpp>
+#include <yycc/windows/import_guard_head.hpp>
 #include <Windows.h>
 #include "other_header_depend_on_windows.h"
-#include <WinImportSuffix.hpp>
+#include <yycc/windows/import_guard_tail.hpp>
 #endif
 \endcode
 
-The including of WinImportPrefix.hpp and WinImportSuffix.hpp is a pair.
+The including of import_guard_head.hpp and import_guard_tail.hpp is a pair.
 They just like a guard bracket the include operation of Windows related headers,
 to keep all Windows shitty contents will not be leaked outside.
 
@@ -30,7 +32,7 @@ This guard can solve following issues:
     Programmer can not use \c std::max and \c std::min normally.
     <UL>
         <LI>Windows defines \c MAX and \c MIN as macros for personal use. This is why this happened.</LI>
-        <LI>Guard defines some special macros to tell Windows do not create these 2 macros.</LI>
+        <LI>This is actually resolved by CMake defined 2 public build macros which tell Windows do not create these 2 macros. But I simply conclude this feature in there.</LI>
     </UL>
     </LI>
     <LI>
@@ -44,12 +46,12 @@ This guard can solve following issues:
     Compiler throw annoy warnings and errors when using specific standard library functions.
     <UL>
         <LI>MSVC will throw warnings and errors when you are using Microsoft so-called \e depracted or \e unsafe standard library functions.</LI>
-        <LI>YYCCInternal.hpp, which has been included by this pair, defines some macros to purge these warnings and errors out.</LI>
+        <LI>This is also done by CMake public build macros.</LI>
     </UL>
     </LI>
 </UL>
 
-\section win_import__notes Notes
+\section windows__import_guard__notes Notes
 
 If you have other header files which are strongly depend on Windows header,
 you should put them into this bracket at the same time like example did.