<xstddef>: document code-emitting function-like macros

[CaseyCarter]

At the end of <xstddef>:

STL/stl/inc/xstddef

Lines 293 to 422 in 1d39dfa

	#define _EMIT_CDECL(FUNC, OPT1, OPT2, OPT3) FUNC(__cdecl, OPT1, OPT2, OPT3)
	#ifdef _M_CEE
	#define _EMIT_CLRCALL(FUNC, OPT1, OPT2, OPT3) FUNC(__clrcall, OPT1, OPT2, OPT3)
	#else // _M_CEE
	#define _EMIT_CLRCALL(FUNC, OPT1, OPT2, OPT3)
	#endif // _M_CEE
	#if defined(_M_IX86) && !defined(_M_CEE)
	#define _EMIT_FASTCALL(FUNC, OPT1, OPT2, OPT3) FUNC(__fastcall, OPT1, OPT2, OPT3)
	#else // defined(_M_IX86) && !defined(_M_CEE)
	#define _EMIT_FASTCALL(FUNC, OPT1, OPT2, OPT3)
	#endif // defined(_M_IX86) && !defined(_M_CEE)
	#ifdef _M_IX86
	#define _EMIT_STDCALL(FUNC, OPT1, OPT2, OPT3) FUNC(__stdcall, OPT1, OPT2, OPT3)
	#define _EMIT_THISCALL(FUNC, OPT1, OPT2, OPT3) FUNC(__thiscall, OPT1, OPT2, OPT3)
	#else // _M_IX86
	#define _EMIT_STDCALL(FUNC, OPT1, OPT2, OPT3)
	#define _EMIT_THISCALL(FUNC, OPT1, OPT2, OPT3)
	#endif // _M_IX86
	#if ((defined(_M_IX86) && _M_IX86_FP >= 2) || defined(_M_X64)) && !defined(_M_CEE)
	#define _EMIT_VECTORCALL(FUNC, OPT1, OPT2, OPT3) FUNC(__vectorcall, OPT1, OPT2, OPT3)
	#else // defined(_M_IX86) && _M_IX86_FP >= 2 etc.
	#define _EMIT_VECTORCALL(FUNC, OPT1, OPT2, OPT3)
	#endif // defined(_M_IX86) && _M_IX86_FP >= 2 etc.
	#define _NON_MEMBER_CALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_CDECL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_CLRCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_FASTCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_STDCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_VECTORCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT)
	#define _NON_MEMBER_CALL_CV(FUNC, REF_OPT, NOEXCEPT_OPT) \
	_NON_MEMBER_CALL(FUNC, , REF_OPT, NOEXCEPT_OPT) \
	_NON_MEMBER_CALL(FUNC, const, REF_OPT, NOEXCEPT_OPT) \
	_NON_MEMBER_CALL(FUNC, volatile, REF_OPT, NOEXCEPT_OPT) \
	_NON_MEMBER_CALL(FUNC, const volatile, REF_OPT, NOEXCEPT_OPT)
	#define _NON_MEMBER_CALL_CV_REF(FUNC, NOEXCEPT_OPT) \
	_NON_MEMBER_CALL_CV(FUNC, , NOEXCEPT_OPT) \
	_NON_MEMBER_CALL_CV(FUNC, &, NOEXCEPT_OPT) \
	_NON_MEMBER_CALL_CV(FUNC, &&, NOEXCEPT_OPT)
	#ifdef __cpp_noexcept_function_type
	#define _NON_MEMBER_CALL_CV_REF_NOEXCEPT(FUNC) \
	_NON_MEMBER_CALL_CV_REF(FUNC, ) \
	_NON_MEMBER_CALL_CV_REF(FUNC, noexcept)
	#else // __cpp_noexcept_function_type
	#define _NON_MEMBER_CALL_CV_REF_NOEXCEPT(FUNC) _NON_MEMBER_CALL_CV_REF(FUNC, )
	#endif // __cpp_noexcept_function_type
	#define _MEMBER_CALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_CDECL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_CLRCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_FASTCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_STDCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_THISCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT) \
	_EMIT_VECTORCALL(FUNC, CV_OPT, REF_OPT, NOEXCEPT_OPT)
	#define _MEMBER_CALL_CV(FUNC, REF_OPT, NOEXCEPT_OPT) \
	_MEMBER_CALL(FUNC, , REF_OPT, NOEXCEPT_OPT) \
	_MEMBER_CALL(FUNC, const, REF_OPT, NOEXCEPT_OPT) \
	_MEMBER_CALL(FUNC, volatile, REF_OPT, NOEXCEPT_OPT) \
	_MEMBER_CALL(FUNC, const volatile, REF_OPT, NOEXCEPT_OPT)
	#define _MEMBER_CALL_CV_REF(FUNC, NOEXCEPT_OPT) \
	_MEMBER_CALL_CV(FUNC, , NOEXCEPT_OPT) \
	_MEMBER_CALL_CV(FUNC, &, NOEXCEPT_OPT) \
	_MEMBER_CALL_CV(FUNC, &&, NOEXCEPT_OPT)
	#ifdef __cpp_noexcept_function_type
	#define _MEMBER_CALL_CV_REF_NOEXCEPT(FUNC) \
	_MEMBER_CALL_CV_REF(FUNC, ) \
	_MEMBER_CALL_CV_REF(FUNC, noexcept)
	#else // __cpp_noexcept_function_type
	#define _MEMBER_CALL_CV_REF_NOEXCEPT(FUNC) _MEMBER_CALL_CV_REF(FUNC, )
	#endif // __cpp_noexcept_function_type
	#define _CLASS_DEFINE_CONST(CLASS) \
	CLASS(_EMPTY_ARGUMENT) \
	CLASS(const)
	#ifdef __cpp_noexcept_function_type
	#define _CLASS_DEFINE_CV_REF_NOEXCEPT(CLASS) \
	CLASS(_EMPTY_ARGUMENT) \
	CLASS(const) \
	CLASS(volatile) \
	CLASS(const volatile) \
	CLASS(&) \
	CLASS(const&) \
	CLASS(volatile&) \
	CLASS(const volatile&) \
	CLASS(&&) \
	CLASS(const&&) \
	CLASS(volatile&&) \
	CLASS(const volatile&&) \
	CLASS(noexcept) \
	CLASS(const noexcept) \
	CLASS(volatile noexcept) \
	CLASS(const volatile noexcept) \
	CLASS(&noexcept) \
	CLASS(const& noexcept) \
	CLASS(volatile& noexcept) \
	CLASS(const volatile& noexcept) \
	CLASS(&&noexcept) \
	CLASS(const&& noexcept) \
	CLASS(volatile&& noexcept) \
	CLASS(const volatile&& noexcept)
	#else // __cpp_noexcept_function_type
	#define _CLASS_DEFINE_CV_REF_NOEXCEPT(CLASS) \
	CLASS(_EMPTY_ARGUMENT) \
	CLASS(const) \
	CLASS(volatile) \
	CLASS(const volatile) \
	CLASS(&) \
	CLASS(const&) \
	CLASS(volatile&) \
	CLASS(const volatile&) \
	CLASS(&&) \
	CLASS(const&&) \
	CLASS(volatile&&) \
	CLASS(const volatile&&)
	#endif // __cpp_noexcept_function_type

we define a small system of macros that are used to stamp out small variations of code for particular cv qualifiers, or calling conventions, etc. We go out of our way to avoid these macros in new code, but there are nevertheless some existing uses. It would be nice to document these macros and their usage via comments in the header.