doc: update documentation for FsPathPatch

doc/src/fs_path_patch.dox

@@ -2,4 +2,72 @@
 
 \page fs_path_patch std::filesystem::path Patch
 
+As you know, the underlying char type of \c std::filesystem::path is \c wchar_t on Windows,
+and in other platforms, it is simple \c char.
+Due to this, if you try to create a \c std::filesystem::path instance by calling constructor with an UTF8 char sequence on Windows,
+the library implementation will assume your input is based on current Windows code page, not UTF8.
+And the final path stored in \c std::filesystem::path is not what you expcected.
+
+This patch gives you a way to create \c std::filesystem::path 
+and extract path string stored in \c std::filesystem::path with UTF8 encoding.
+This patch namespace always use UTF8 as its argument.
+You should use the functions provided by this namespace on any platforms 
+instead of vanilla \c std::filesystem::path functions.
+However, if your C++ standard is higher than C++ 20,
+you can directly use UTF8 string pointer and string container in \c std::filesystem::path,
+because standard library has supported them.
+This patch only just want to provide an uniform programming experience.
+
+This patch is served for Windows but also works on other plaftoms.
+If you are in Windows, this patch will perform extra operations to achieve goals,
+and in other platforms, they just redirect request to corresponding vanilla C++ functions.
+
+\section fs_path_patch__from_utf8_path Create Path from UTF8 String
+
+YYCC::FsPathPatch::FromUTF8Path provides this feature.
+It accepts an string pointer to UTF8 string and try to create \c std::filesystem::path from it.
+Function will throw exception if encoding convertion or constructor self failed.
+There are some example:
+
+\code
+auto foobar_path = YYCC::FsPathPatch::FromUTF8Path(YYCC_U8("/foo/bar"));
+auto slashed_path = foobar_path / YYCC::FsPathPatch::FromUTF8Path(YYCC_U8("test"));
+auto replaced_ext = foobar_path.replace_extension(YYCC::FsPathPatch::FromUTF8Path(YYCC_U8(".txt")));
+\endcode
+
+For first line in example, it is obvious that you can create a \c std::filesystem::path from this function.
+However, for the second and third line in example, what we want to tell you is 
+that you should always use this function in other \c std::filesystem::path functions requiring path string.
+
+\c std::filesystem::path is a very \e conservative class.
+Most of its functions only accept \c std::filesystem::path self as argument.
+For example, \c std::filesystem::path::replace_extension do not accept string as argument.
+It accepts a reference to \c std::filesystem::path as argument.
+(it still is possible that pass string pointer or string container to it because they can be converted to \c std::filesystem::path implicitly.)
+It's great. This is what we expected!
+We now can safely deliver the result generated by our function to these functions,
+and don't need to worry about the encoding of we provided string.
+Because all strings have been converted to \c std::filesystem::path by our function before passing them.
+
+So, the second line will produce \c "/foo/bar/test" 
+and the third line will produce \c "/foo/bar.txt" in any platforms.
+
+You may notice std::filesystem::u8path.
+However it is depracted since C++ 20,
+because \c std::filesystem::path directly supports UTF8 by \c char8_t since C++ 20.
+Because C++ standard is volatile, we create this function to have an uniform programming experience.
+
+\section fs_path_patch__to_utf8_path Extract UTF8 Path String from Path
+
+YYCC::FsPathPatch::ToUTF8Path provides this feature.
+It basically is the reversed operation of YYCC::FsPathPatch::FromUTF8Path.
+It is usually used when you have done all path work in \c std::filesystem::path
+and want to get the result.
+There is an example:
+
+\code
+auto foobar_path = YYCC::FsPathPatch::FromUTF8Path(YYCC_U8("/foo/bar"));
+auto result = YYCC::FsPathPatch::ToUTF8Path(foobar_path / YYCC::FsPathPatch::FromUTF8Path(YYCC_U8("test")));
+\endcode
+
 */