Merge pull request #10824 from haskell/fix10819

Fix #10819 Document that executables etc can depend on library in same package

Author: mergify[bot]

doc/cabal-package-description-file.rst

@@ -1353,6 +1353,15 @@ system-dependent values for these fields.
     from the same package can be specified with the shorthand syntax
     ``my-package:{my-library1,my-library2}``.
 
+    .. Note::
+
+       The :pkg-field:`build-depends` field of an executable section (from
+       version 1.8 of the Cabal specification), test suite section (from
+       version 1.10) or benchmark section (from version 1.14) can specify a
+       library in the same package by the name of the library (without a version
+       constraint). Cabal then treats the executable, test suite or benchmark as
+       if it were in another package that depended on the package.
+
     .. Note::
 
        Before version 3.4 of the Cabal specification, from version 2.0, a
@@ -2317,7 +2326,7 @@ Configurations
 
 Library and executable sections may include conditional blocks, which
 test for various system parameters and configuration flags. The flags
-mechanism is rather generic, but most of the time a flag represents
+mechanism is rather generic, but most of the time a flag represents a
 certain feature, that can be switched on or off by the package user.
 Here is an example package description file using configurations:
 
@@ -2378,8 +2387,9 @@ Example: A package containing a library and executable programs
 
     Executable test1
       Main-is:          T1.hs
-      Other-Modules:    Testing.Test1
-      Build-Depends:    base >= 4.2 && < 4.9
+      Build-Depends:
+        , base >= 4.2 && < 4.9
+        , Test1
       Default-Language: Haskell2010
 
       if flag(debug)