diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst
index b8dab19a5d5..54375877002 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -1188,6 +1188,13 @@ Dynamic linking options
     Build shared library. This implies a separate compiler run to
     generate position independent code as required on most platforms.
 
+    ``--enable-shared`` is enabled automatically if GHC is dynamically linked
+    (see ``ghc --info``'s ``GHC Dynamic`` field)
+    or you request to build dynamic executables.
+
+    If you want to build *only* dynamic object files,
+    you also have to pass ``--disable-library-vanilla``.
+
     The command line variant of this flag is ``--enable-shared`` and
     ``--disable-shared``.
 
diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst
index 970439e748d..a42d7053659 100644
--- a/doc/setup-commands.rst
+++ b/doc/setup-commands.rst
@@ -807,8 +807,12 @@ Miscellaneous options
     Build shared library. This implies a separate compiler run to
     generate position independent code as required on most platforms.
 
-    ``--enable-shared`` is enabled automatically if GHC is dynamically linked or
-    you request to build dynamic executables.
+    ``--enable-shared`` is enabled automatically if GHC is dynamically linked
+    (see ``ghc --info``'s ``GHC Dynamic`` field)
+    or you request to build dynamic executables.
+
+    If you want to build *only* dynamic object files,
+    you also have to pass ``--disable-library-vanilla``.
 
 .. option:: --disable-shared