diff --git a/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst
index 619377a11c..77f8311a89 100644
--- a/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst
+++ b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst
@@ -10,3 +10,15 @@ the modules will be placed.  When this property is not set, the modules will be
 placed in the build directory corresponding to the target's source directory.
 If the variable :variable:`CMAKE_Swift_MODULE_DIRECTORY` is set when a target is
 created its value is used to initialize this property.
+
+.. warning::
+
+  This property does not currently provide a way to express per-config
+  module directories, so use with multi-config generators is problematic:
+
+  * The :generator:`Xcode` generator does not implement the property at all.
+
+  * The :generator:`Ninja Multi-Config` generator implements this property,
+    but module files generated for different build configurations have the
+    same path, which can lead to subtle problems when building more than
+    one configuration.