[libc++] Clarify _LIBCPP_NEW_DELETE_VIS for Windows

[smeenai]

Summary

Replace a stale reference to cxx_EXPORTS with _LIBCPP_BUILDING_LIBRARY,
and clarify why the operator new and delete family of functions are
marked dllexport when building but *not* dllimport when including the
header externally.

The new code is identical to the intent of the old code (and would be
functionally equivalent were cxx_EXPORTS still defined when building
libc++). The overall behavior is not ideal, since Microsoft's operator
new and delete functions will get called instead of libc++'s, but I
think consistently calling msvcrt's functions is better than either
calling msvcrt's or libc++'s functions depending on header inclusion.

[smeenai]

Clarifying code comment

[EricWF]

LGTM modulo inline comments.

include/new

129

Could you put this documentation in VisibilityMacros.rst instead of in the headers?

[smeenai]

Moving documentation to documentation file, per @EricWF's comment

include/new

 struct _LIBCPP_TYPE_VIS nothrow_t {};
 extern _LIBCPP_FUNC_VIS const nothrow_t nothrow;
 typedef void (*new_handler)();
 _LIBCPP_FUNC_VIS new_handler set_new_handler(new_handler) _NOEXCEPT;
 _LIBCPP_FUNC_VIS new_handler get_new_handler() _NOEXCEPT;
 
 }  // std
 
-#if defined(_WIN32) && !defined(cxx_EXPORTS)
-# define _LIBCPP_NEW_DELETE_VIS _LIBCPP_FUNC_VIS_ONLY
+/*
+ * NOTE: When using the Microsoft CRT, the operator new and delete
+ * family of functions are defined statically in msvcrt.lib. Marking
+ * them as dllimport in this header is therefore undesirable: if we were
+ * to mark them dllimport and then link against libc++, source files
+ * which included <new> would end up linking against libc++'s new and
+ * delete, while source files which did not include <new> would end up
+ * still linking against msvcrt's new, which would be a confusing and
+ * potentially error-prone inconsistency.
+ */
+#if defined(_LIBCPP_MSVCRT) && !defined(_LIBCPP_BUILDING_LIBRARY)
+# define _LIBCPP_NEW_DELETE_VIS
 #else
 # define _LIBCPP_NEW_DELETE_VIS _LIBCPP_FUNC_VIS
 #endif
 
 _LIBCPP_NEW_DELETE_VIS void* operator new(std::size_t __sz)
 #if !__has_feature(cxx_noexcept)
     throw(std::bad_alloc)
 #endif