diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst
index baac75e06f9..1bf238063c7 100644
--- a/doc/cabal-project-description-file.rst
+++ b/doc/cabal-project-description-file.rst
@@ -193,9 +193,11 @@ Formally, the format is described by the following BNF:
 Specifying Packages from Remote Version Control Locations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Starting with Cabal 2.4, there is now a stanza
-``source-repository-package`` for specifying packages from an external
-version control.
+Since version 2.4, the ``source-repository-package`` stanza allows for
+specifying packages in a remote version control system that cabal should
+consider during package retrieval. This allows use of a package from a
+remote version control system, rather than looking for that package in
+Hackage.
 
 .. code-block:: cabal
 
@@ -218,8 +220,11 @@ version control.
         tag: e76fdc753e660dfa615af6c8b6a2ad9ddf6afe70
         post-checkout-command: autoreconf -i
 
-cabal-install 3.4 sdists the ``source-repository-package`` repositories and uses resulting tarballs as project packages.
-This allows sharing of packages across different projects.
+Since version 3.4, cabal-install creates tarballs for each package coming
+from a ``source-repository-package`` stanza (effectively applying cabal
+sdists to such packages). It gathers the names of the packages from the
+appropriate .cabal file in the version control repository, and allows
+their use just like Hackage or locally defined packages.
 
 .. cfg-field:: type: VCS kind
 
@@ -229,7 +234,7 @@ This allows sharing of packages across different projects.
 
 .. cfg-field:: subdir: subdirectory list
 
-    Use one or more subdirectories of the repository.
+    Look in one or more subdirectories of the repository for cabal files, rather than the root.
 
 .. cfg-field:: post-checkout-command: command