Add Cabal synopses and descriptions

Various people (myself included) have complained about the lack of
useful descriptions for the various packages included in GHC's source
tree. Fix this.

Test Plan: Validate

Reviewers: austin, thomie

Reviewed By: thomie

Subscribers: angerman, ezyang

Differential Revision: https://phabricator.haskell.org/D1736

12 files changed, 63 insertions, 22 deletions

diff --git a/utils/check-api-annotations/check-api-annotations.cabal b/utils/check-api-annotations/check-api-annotations.cabal
index 38c3f184f1..ade5fe451f 100644
--- a/utils/check-api-annotations/check-api-annotations.cabal
+++ b/utils/check-api-annotations/check-api-annotations.cabal
@@ -5,8 +5,12 @@ License: BSD3
 -- XXX License-File: LICENSE
 Author: XXX
 Maintainer: XXX
-Synopsis: XXX
-Description: XXX
+Synopsis: A utilities for checking the consistency of GHC's API annotations.
+Description:
+    This utility is used to check the consistency between GHC's syntax tree
+    and API annotations used to track token-level details of the original
+    source file. See @utils/check-api-annotations/README@ in GHC's source
+    distribution for details.
 Category: Development
 build-type: Simple
 cabal-version: >=1.10
diff --git a/utils/compare_sizes/compareSizes.cabal b/utils/compare_sizes/compareSizes.cabal
index f8f42636a7..04b3a58776 100644
--- a/utils/compare_sizes/compareSizes.cabal
+++ b/utils/compare_sizes/compareSizes.cabal
@@ -5,8 +5,9 @@ license:              BSD3
 build-type:           Simple
 license-file:         LICENSE
 stability:            experimental
-synopsis:             Size comparison util
-description:          Size comparison util
+synopsis:             Size comparison utility.
+description:          A small utility for comparing the sizes of files used by
+                      the GHC build system.
 category:             Development
 
 executable compareSizes
diff --git a/utils/deriveConstants/deriveConstants.cabal b/utils/deriveConstants/deriveConstants.cabal
index 72afb72c80..50b5b695c3 100644
--- a/utils/deriveConstants/deriveConstants.cabal
+++ b/utils/deriveConstants/deriveConstants.cabal
@@ -5,8 +5,11 @@ License: BSD3
 -- XXX License-File: LICENSE
 Author: XXX
 Maintainer: XXX
-Synopsis: XXX
-Description: XXX
+Synopsis: Derive header files containing various constants for the GHC build process
+Description:
+    This utility is responsible for generating a number of C header files
+    needed during the GHC build process. See @includes/ghc.mk@ in the GHC
+    build system for details.
 Category: Development
 build-type: Simple
 cabal-version: >=1.10
diff --git a/utils/dll-split/dll-split.cabal b/utils/dll-split/dll-split.cabal
index 290af06472..8730b4fcdc 100644
--- a/utils/dll-split/dll-split.cabal
+++ b/utils/dll-split/dll-split.cabal
@@ -5,9 +5,15 @@ License: BSD3
 -- XXX License-File: LICENSE
 Author: XXX
 Maintainer: XXX
-Synopsis: XXX
+Synopsis: A tool for verifying the partitioning of the GHC library on Windows
 Description:
-	XXX
+    Due to various toolchain issues (see GHC Trac #5987) we are forced to keep
+    DLLs on Windows smaller than 65,000 symbols. To accomplish this we split
+    the @ghc@ package into multiple DLLs by partitioning defined in the
+    build system (see @compiler/ghc.mk@).
+    .
+    This tool checks this partitioning to ensure consistency with the actual
+    module dependencies.
 Category: Development
 build-type: Simple
 cabal-version: >=1.10
diff --git a/utils/genapply/genapply.cabal b/utils/genapply/genapply.cabal
index dba3b6d166..8926db1178 100644
--- a/utils/genapply/genapply.cabal
+++ b/utils/genapply/genapply.cabal
@@ -5,9 +5,12 @@ License: BSD3
 -- XXX License-File: LICENSE
 -- XXX Author:
 -- XXX Maintainer:
-Synopsis: XXX
+Synopsis: Generate the application closures
 Description:
-  XXX
+    This script is responsible for generating the @AutoApply.cmm@ source
+    file during the build process of GHC's runtime system. This file
+    defines the standard closures used to represent application of functions
+    of various arities.
 build-type: Simple
 cabal-version: >=1.10
 
diff --git a/utils/genprimopcode/genprimopcode.cabal b/utils/genprimopcode/genprimopcode.cabal
index adc5230a4f..d6dc8b58ec 100644
--- a/utils/genprimopcode/genprimopcode.cabal
+++ b/utils/genprimopcode/genprimopcode.cabal
@@ -5,8 +5,14 @@ License: BSD3
 -- XXX License-File: LICENSE
 Author: XXX
 Maintainer: XXX
-Synopsis: XXX
-Description: XXX
+Synopsis: Generates various files implementing GHC's primitive operations.
+Description:
+    This utility reads a textual description of GHC's primitive operations
+    (@primops.txt.pp@) and produces a number of outputs. These include,
+    .
+    * the @GHC.Prim@ module included in the @ghc-prim@ package.
+    * the @GHC.PrimopWrappers@ module included in the @ghc-prim@ package.
+    * an LaTeX document describing the primitive operations.
 Category: Development
 build-type: Simple
 cabal-version: >=1.10
diff --git a/utils/ghc-cabal/Main.hs b/utils/ghc-cabal/Main.hs
index 680c573107..2c05da83a7 100644
--- a/utils/ghc-cabal/Main.hs
+++ b/utils/ghc-cabal/Main.hs
@@ -409,7 +409,7 @@ generate directory distdir dll0Modules config_args
                 variablePrefix ++ "_COMPONENT_ID = " ++ display (localCompatPackageKey lbi),
                 variablePrefix ++ "_MODULES = " ++ unwords mods,
                 variablePrefix ++ "_HIDDEN_MODULES = " ++ unwords otherMods,
-                variablePrefix ++ "_SYNOPSIS =" ++ synopsis pd,
+                variablePrefix ++ "_SYNOPSIS =" ++ (unwords $ lines $ synopsis pd),
                 variablePrefix ++ "_HS_SRC_DIRS = " ++ unwords (hsSourceDirs bi),
                 variablePrefix ++ "_DEPS = " ++ unwords deps,
                 variablePrefix ++ "_DEP_IPIDS = " ++ unwords dep_ipids,
diff --git a/utils/ghc-cabal/ghc-cabal.cabal b/utils/ghc-cabal/ghc-cabal.cabal
index 1697f7cebc..d6048a3cb2 100644
--- a/utils/ghc-cabal/ghc-cabal.cabal
+++ b/utils/ghc-cabal/ghc-cabal.cabal
@@ -5,8 +5,12 @@ License: BSD3
 -- XXX License-File: LICENSE
 Author: XXX
 Maintainer: XXX
-Synopsis: XXX
-Description: XXX
+Synopsis: A utility for producing package metadata from Cabal package
+          descriptions for GHC's build system
+Description: This program is responsible for producing @package-data.mk@ files
+             for Cabal packages. These files are used by GHC's @make@-based
+             build system to determine the source files included by package,
+             package dependencies, and other metadata.
 Category: Development
 build-type: Simple
 cabal-version: >=1.10
diff --git a/utils/ghc-pkg/ghc-pkg.cabal b/utils/ghc-pkg/ghc-pkg.cabal
index aca0783474..5f76e1b5ee 100644
--- a/utils/ghc-pkg/ghc-pkg.cabal
+++ b/utils/ghc-pkg/ghc-pkg.cabal
@@ -6,8 +6,11 @@ License: BSD3
 -- XXX License-File: LICENSE
 Author: XXX
 Maintainer: cvs-fptools@haskell.org
-Synopsis: XXX
-Description: XXX
+Synopsis: A utility for querying and managing the GHC package database.
+Description:
+    GHC maintains a database of known packages. This tools allows tools
+    and users to query and modify this database. See @ghc-pkg --help@ for
+    usage information.
 Category: Development
 build-type: Simple
 cabal-version: >=1.10
diff --git a/utils/ghctags/ghctags.cabal b/utils/ghctags/ghctags.cabal
index 7901aa254c..d73c7fa0ee 100644
--- a/utils/ghctags/ghctags.cabal
+++ b/utils/ghctags/ghctags.cabal
@@ -5,7 +5,7 @@ License: BSD3
 -- XXX License-File: LICENSE
 Author: XXX
 Maintainer: XXX
-Synopsis: XXX
+Synopsis: A simple generator of vi- and emacs-compatible TAGS files.
 Description: XXX
 Category: Development
 build-type: Simple
diff --git a/utils/mkUserGuidePart/mkUserGuidePart.cabal b/utils/mkUserGuidePart/mkUserGuidePart.cabal
index 5b185ee30d..93dc1cfec0 100644
--- a/utils/mkUserGuidePart/mkUserGuidePart.cabal
+++ b/utils/mkUserGuidePart/mkUserGuidePart.cabal
@@ -5,9 +5,10 @@ License: BSD3
 -- XXX License-File: LICENSE
 -- XXX Author:
 -- XXX Maintainer:
-Synopsis: XXX
+Synopsis: Generate various portions of GHC's documentation
 Description:
-	XXX
+    This tool is responsible for producing ReStructuredText sources which
+    are included in GHC's user's guide and manpage.
 build-type: Simple
 cabal-version: >=1.10
 
diff --git a/utils/runghc/runghc.cabal.in b/utils/runghc/runghc.cabal.in
index 47fb83dc08..efef5ec4db 100644
--- a/utils/runghc/runghc.cabal.in
+++ b/utils/runghc/runghc.cabal.in
@@ -5,9 +5,19 @@ License: BSD3
 -- XXX License-File: LICENSE
 Author: XXX
 Maintainer: XXX
-Synopsis: XXX
+Synopsis: A wrapper around GHC allowing convenient execution of scripts
 Description:
-	XXX
+    @runghc@ is a small wrapper program around GHC which allows the compiler
+    to be used as a UNIX-style script interpreter. For instance,
+    .
+    @
+    $ cat > Hi.hs
+    \#!/usr/bin/env runghc
+    main = putStrLn "hello!"
+    $ chmod u+x Hi.hs
+    $ ./Hi.hs
+    hello!
+    @
 Category: Development
 build-type: Simple
 cabal-version: >=1.10