dox: add WinImport pair documentation
This commit is contained in:
parent
588946583c
commit
e2a582e7d2
5
doc/src/config_manager.dox
Normal file
5
doc/src/config_manager.dox
Normal file
|
@ -0,0 +1,5 @@
|
||||||
|
/**
|
||||||
|
|
||||||
|
\page config_manager Universal Config Manager
|
||||||
|
|
||||||
|
*/
|
|
@ -33,10 +33,12 @@
|
||||||
|
|
||||||
\subpage string_helper
|
\subpage string_helper
|
||||||
|
|
||||||
|
\subpage win_import
|
||||||
|
|
||||||
</TD>
|
</TD>
|
||||||
<TD ALIGN="LEFT" VALIGN="TOP">
|
<TD ALIGN="LEFT" VALIGN="TOP">
|
||||||
|
|
||||||
placeholder
|
\subpage config_manager
|
||||||
|
|
||||||
</TD>
|
</TD>
|
||||||
</TR>
|
</TR>
|
||||||
|
|
56
doc/src/win_import.dox
Normal file
56
doc/src/win_import.dox
Normal file
|
@ -0,0 +1,56 @@
|
||||||
|
/**
|
||||||
|
|
||||||
|
\page win_import 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.
|
||||||
|
YYCC has a way to solve this issue.
|
||||||
|
|
||||||
|
\code
|
||||||
|
#include <WinImportPrefix.hpp>
|
||||||
|
#include <Windows.h>
|
||||||
|
#include "other_header_depend_on_windows.h"
|
||||||
|
#include <WinImportSuffix.hpp>
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
The including of WinImportPrefix.hpp and WinImportSuffix.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.
|
||||||
|
|
||||||
|
This guard can solve following issues:
|
||||||
|
|
||||||
|
<UL>
|
||||||
|
<LI>
|
||||||
|
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 happend.</LI>
|
||||||
|
<LI>Guard defines some special macros to tell Windows do not create these 2 macros.</LI>
|
||||||
|
</UL>
|
||||||
|
</LI>
|
||||||
|
<LI>
|
||||||
|
Programmer will not be affected by the automatical rename of \c GetObject, \c GetClassName and etc.
|
||||||
|
<UL>
|
||||||
|
<LI>These are all macros for Windows personal use to automatically redirect calling to A function and W function by compiling environment.</LI>
|
||||||
|
<LI>Guard \c #undef these annoy macros.</LI>
|
||||||
|
</UL>
|
||||||
|
</LI>
|
||||||
|
<LI>
|
||||||
|
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>
|
||||||
|
</UL>
|
||||||
|
</LI>
|
||||||
|
</UL>
|
||||||
|
|
||||||
|
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.
|
||||||
|
Because this guard operate some Windows macros as we introduced above.
|
||||||
|
The headers depending on Windows may throw error if you put them outside of this pair.
|
||||||
|
|
||||||
|
Please note WinImportPrefix.hpp and WinImportSuffix.hpp can be included multiple times.
|
||||||
|
Because they do not have the proprocessor command like <I>#pragma once</I> or etc to make sure they only can be included once.
|
||||||
|
That's by design. Because we actually may use this pair multiple times.
|
||||||
|
The only thing you should pledge is that you must make sure they are presented by pair.
|
||||||
|
|
||||||
|
*/
|
Loading…
Reference in New Issue
Block a user