[libcxx] Slightly improved policy for handling experimental features

Summary:
Following the discussion on the libcxx-dev mailing list
(http://lists.llvm.org/pipermail/libcxx-dev/2019-May/000358.html),
this implements the new policy for handling experimental features and
their deprecation. We basically add a deprecation warning for
std::experimental::filesystem, and we remove a bunch of <experimental/*>
headers that were now empty.

Reviewers: mclow.lists, EricWF

Subscribers: mgorny, christof, jkorous, dexonsmith, arphaman, libcxx-commits, jfb

Tags: #libc

Differential Revision: https://reviews.llvm.org/D62428

git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@363072 91177308-0d34-0410-b5e6-96231b3b80d8

Author: ldionne

docs/DesignDocs/ExperimentalFeatures.rst

@@ -84,6 +84,9 @@ page.
     * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a``
       library will not remain compatible between versions.
     * No guarantees of API or ABI stability are provided.
+    * When we implement the standardized version of an experimental feature,
+      the experimental feature is removed two releases after the non-experimental
+      version has shipped. The full policy is explained :ref:`here <experimental features>`.
 
 Using libc++ on Linux
 =====================

docs/UsingLibcxx.rst

@@ -137,6 +137,7 @@ Design Documents
    DesignDocs/DebugMode
    DesignDocs/CapturingConfigInfo
    DesignDocs/ABIVersioning
+   DesignDocs/ExperimentalFeatures
    DesignDocs/VisibilityMacros
    DesignDocs/ThreadingSupportAPI
    DesignDocs/FileTimeType

docs/index.rst

@@ -65,8 +65,6 @@ set(files
   experimental/__config
   experimental/__memory
   experimental/algorithm
-  experimental/any
-  experimental/chrono
   experimental/coroutine
   experimental/deque
   experimental/filesystem
@@ -76,17 +74,11 @@ set(files
   experimental/list
   experimental/map
   experimental/memory_resource
-  experimental/numeric
-  experimental/optional
   experimental/propagate_const
-  experimental/ratio
   experimental/regex
   experimental/set
   experimental/simd
   experimental/string
-  experimental/string_view
-  experimental/system_error
-  experimental/tuple
   experimental/type_traits
   experimental/unordered_map
   experimental/unordered_set

include/CMakeLists.txt

@@ -36,8 +36,14 @@
   namespace chrono { namespace experimental { inline namespace fundamentals_v1 {
 #define _LIBCPP_END_NAMESPACE_CHRONO_LFTS _LIBCPP_END_NAMESPACE_STD } } }
 
+#if defined(_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_FILESYSTEM)
+#   define _LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM /* nothing */
+#else
+#   define _LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM __attribute__((deprecated("std::experimental::filesystem has now been deprecated in favor of C++17's std::filesystem. Please stop using it and start using std::filesystem. This experimental version will be removed in LLVM 11. You can remove this warning by defining the _LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_FILESYSTEM macro.")))
+#endif
+
 #define _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL_FILESYSTEM \
-    _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL namespace filesystem { \
+    _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL namespace filesystem _LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM { \
     inline namespace v1 {
 
 #define _LIBCPP_END_NAMESPACE_EXPERIMENTAL_FILESYSTEM \