yyc12345/YYCCommonplace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: update documentation

Browse Source 
- use namespace bracket all content in documentation to reduce useless namespace prefix.
- change the argument type of AbstractSetting and CoreManager to yycc_u8string_view instead of const yycc_char8_t*.
- throw exception if given setting name is invalid in ConfigManager, instead of slient fallback.
This commit is contained in:
yyc12345
2024-07-31 14:14:38 +08:00
parent 598aae69ae
commit 1cfbcb3b18
15 changed files with 142 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
doc/src/encoding_helper.dox
View File

@ -1,3 +1,4 @@
namespace YYCC::EncodingHelper {
/**
\page encoding_helper Encoding Helper
@ -15,10 +16,10 @@ See \ref library_encoding for more infomation.
YYCC supports following convertions:
\li YYCC::EncodingHelper::ToUTF8: Convert ordinary string to UTF8 string.
\li YYCC::EncodingHelper::ToUTF8View: Same as ToUTF8, but return string view instead.
\li YYCC::EncodingHelper::ToOrdinary: Convert UTF8 string to ordinary string.
\li YYCC::EncodingHelper::ToOrdinaryView: Same as ToOrdinary, but return string view instead.
\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
@ -32,13 +33,13 @@ Please use them carefully (make sure that you are using them only in Windows env
YYCC supports following convertions:
\li YYCC::EncodingHelper::WcharToChar: Convert \c wchar_t string to code page specified string.
\li YYCC::EncodingHelper::CharToWchar: The reversed convertion of WcharToChar.
\li YYCC::EncodingHelper::CharToChar: Convert string between 2 different code pages. It's a shortcut of calling CharToWchar and WcharToChar successively.
\li YYCC::EncodingHelper::WcharToUTF8: Convert \c wchar_t string to UTF8 string.
\li YYCC::EncodingHelper::UTF8ToWchar: The reversed convertion of WcharToUTF8.
\li YYCC::EncodingHelper::CharToUTF8: Convert code page specified string to UTF8 string.
\li YYCC::EncodingHelper::UTF8ToChar: The reversed convertion of CharToUTF8.
\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.
@ -55,15 +56,15 @@ They can be used in any platform, not confined in Windows platforms.
YYCC supports following convertions:
\li YYCC::EncodingHelper::UTF8ToUTF16: Convert UTF8 string to UTF16 string.
\li YYCC::EncodingHelper::UTF16ToUTF8: The reversed convertion of UTF8ToUTF16.
\li YYCC::EncodingHelper::UTF8ToUTF32: Convert UTF8 string to UTF32 string.
\li YYCC::EncodingHelper::UTF32ToUTF8: The reversed convertion of UTF8ToUTF32.
\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 YYCC::EncodingHelper::WcharToChar for example.
Take #WcharToChar for example.
There are following 4 overloads:
\code
@ -98,7 +99,7 @@ For the first type, please note that there is \b NO guarantee that the argument
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 YYCC::EncodingHelper::WcharToUTF8, the type of result can be \c yycc_u8string or etc.
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
@ -120,12 +121,12 @@ If you want to process string with \b embedded NUL terminal, please choose first
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 YYCC::EncodingHelper::UTF8ToWchar is \c yycc_u8string_view and \c yycc_char8_t,
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 YYCC::EncodingHelper::WcharToChar.
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.
@ -143,4 +144,5 @@ 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.
*/
*/
}