refactor: refactor doc layout

doc/src/carton/encoding_helper.dox

@@ -0,0 +1,148 @@
+namespace YYCC::EncodingHelper {
+/**
+
+\page encoding_helper Encoding Helper
+
+YYCC::EncodingHelper namespace include all encoding related functions:
+
+\li The convertion between ordinary string and UTF8 string which has been introduced in chapter \ref library_encoding.
+\li Windows specific convertion between \c WCHAR, UTF8 string and string encoded by other encoding.
+\li The convertion among UTF8, UTF16 and UTF32.
+
+\section encoding_helper__ordinary_utf8_conv Ordinary & UTF8 Convertion
+
+These convertion functions have been introduced in previous page.
+See \ref library_encoding for more infomation.
+
+YYCC supports following convertions:
+
+\li #ToUTF8: Convert ordinary string to UTF8 string.
+\li #ToUTF8View: Same as ToUTF8, but return string view instead.
+\li #ToOrdinary: Convert UTF8 string to ordinary string.
+\li #ToOrdinaryView: Same as ToOrdinary, but return string view instead.
+
+\section encoding_helper__win_conv Windows Specific Convertion
+
+During Windows programming, the convertion between Microsoft specified \c wchar_t and \c char is an essential operation.
+Because Windows has 2 different function system, the functions ended with A and the functions ended with W.
+(Microsoft specified \c wchar_t is \c 2 bytes long. It's different with Linux defined common 4 bytes long).
+Thus YYCC provides these convertion functions in Windows to help programmer have better programming experience.
+
+These functions are Windows specific, so they will be invisible in other platforms.
+Please use them carefully (make sure that you are using them only in Windows environment).
+
+YYCC supports following convertions:
+
+\li #WcharToChar: Convert \c wchar_t string to code page specified string.
+\li #CharToWchar: The reversed convertion of WcharToChar.
+\li #CharToChar: Convert string between 2 different code pages. It's a shortcut of calling CharToWchar and WcharToChar successively.
+\li #WcharToUTF8: Convert \c wchar_t string to UTF8 string.
+\li #UTF8ToWchar: The reversed convertion of WcharToUTF8.
+\li #CharToUTF8: Convert code page specified string to UTF8 string.
+\li #UTF8ToChar: The reversed convertion of CharToUTF8.
+
+Code Page is a Windows concept.
+If you don't understand it, please view corresponding Microsoft documentation.
+
+\section encoding_helper__utf_conv UTF8 UTF16 UTF32 Convertion
+
+The convertion between UTF8, UTF16 and UTF32 is not common but essential.
+These convertions can be achieved by standard library functions and classes.
+(they are actually done by standard library functions in our implementation)
+But we provided functions are easy to use and have clear interface.
+
+These functions are different with the functions introduced above.
+They can be used in any platform, not confined in Windows platforms.
+
+YYCC supports following convertions:
+
+\li #UTF8ToUTF16: Convert UTF8 string to UTF16 string.
+\li #UTF16ToUTF8: The reversed convertion of UTF8ToUTF16.
+\li #UTF8ToUTF32: Convert UTF8 string to UTF32 string.
+\li #UTF32ToUTF8: The reversed convertion of UTF8ToUTF32.
+
+\section encoding_helper__overloads Function Overloads
+
+Every encoding convertion functions (except the convertion between UTF8 and ordinary string) have 4 different overloads for different scenarios.
+Take #WcharToChar for example.
+There are following 4 overloads:
+
+\code
+bool WcharToChar(const std::wstring_view& src, std::string& dst, UINT code_page);
+bool WcharToChar(const wchar_t* src, std::string& dst, UINT code_page);
+std::string WcharToChar(const std::wstring_view& src, UINT code_page);
+std::string WcharToChar(const wchar_t* src, UINT code_page);
+\endcode
+
+\subsection encoding_helper__overloads_destination Destination String
+
+According to the return value, these 4 overload can be divided into 2 types.
+The first type returns bool. The second type returns \c std::string instance.
+
+For the first type, it always return bool to indicate whether the convertion is success.
+Due to this, the function must require an argument for holding the result string.
+So you can see the functions belonging to this type always require a reference to \c std::string in argument.
+
+Oppositely, the second directly returns result by return value.
+It doesn't care the success of convertion and will return empty string if convertion failed.
+Programmer can more naturally use it because the retuen value itself is the result.
+There is no need to declare a variable before calling convertion function for holding result.
+
+All in all, the first type overload should be used in strict scope.
+The success of convertion will massively affect the behavior of your following code.
+For example, the convertion code is delivered to some system function and it should not be empty and etc.
+The second type overload usually is used in lossen scenarios.
+For exmaple, this overload usually is used in console output because it usually doesn't matter.
+There is no risk even if the convertion failed (just output a blank string).
+
+For the first type, please note that there is \b NO guarantee that the argument holding return value is not changed.
+Even the convertion is failed, the argument holding return value may still be changed by function itself.
+
+In this case, the type of result is \c std::string because this is function required.
+In other functions, such as #WcharToUTF8, the type of result can be \c yycc_u8string or etc.
+So please note the type of result is decided by convertion function itself, not only \c std::string.
+
+\subsection encoding_helper__overloads__source Source String
+
+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 \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.
+It is compatible with corresponding raw string pointer and string container.
+So it is safe to directly pass \c std::wstring for this function.
+
+For second type, it will assume that you passed argument is a NUL terminated string and send it for convertion.
+
+The result is clear.
+If you want to process string with \b embedded NUL terminal, please choose first type overload.
+Otherwise the second type overload is enough.
+
+Same as destination string, the type of source is also decided by the convertion function itself.
+For exmaple, the type of source in #UTF8ToWchar is \c yycc_u8string_view and \c yycc_char8_t, 
+not \c std::wstring and \c wchar_t.
+
+\subsection encoding_helper__overloads__extra Extra Argument
+
+There is an extra argument called \c code_page for #WcharToChar.
+It indicates the code page of destination string,
+because this function will convert \c wchar_t string to the string with specified code page encoding.
+
+Some convertion functions have extra argument like this,
+because they need more infomations to decide what they need to do.
+Some convertion functions don't have extra argument.
+For exmaple, the convertion between \c wchar_t string and UTF8 string.
+Because both source string and destination string are concrete.
+There is no need to provide any more infomations.
+
+\subsection encoding_helper__overloads__conclusion Conclusion
+
+Mixing 2 types of source string and 2 types of destination string,
+we have 4 different overload as we illustrated before.
+Programmer can use them freely according to your requirements.
+And don't forget to provide extra argument if function required.
+
+*/
+}