Add Cabal synopses and descriptions
authorBen Gamari <bgamari.foss@gmail.com>
Tue, 5 Jan 2016 21:10:01 +0000 (22:10 +0100)
committerBen Gamari <ben@smart-cactus.org>
Tue, 5 Jan 2016 21:10:02 +0000 (22:10 +0100)
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

15 files changed:
ghc/ghc-bin.cabal.in
libraries/ghc-prim/ghc-prim.cabal
libraries/ghci/ghci.cabal.in
utils/check-api-annotations/check-api-annotations.cabal
utils/compare_sizes/compareSizes.cabal
utils/deriveConstants/deriveConstants.cabal
utils/dll-split/dll-split.cabal
utils/genapply/genapply.cabal
utils/genprimopcode/genprimopcode.cabal
utils/ghc-cabal/Main.hs
utils/ghc-cabal/ghc-cabal.cabal
utils/ghc-pkg/ghc-pkg.cabal
utils/ghctags/ghctags.cabal
utils/mkUserGuidePart/mkUserGuidePart.cabal
utils/runghc/runghc.cabal.in

index afb3939..9d4125a 100644 (file)
@@ -9,10 +9,11 @@ Copyright: XXX
 Author: XXX
 Maintainer: glasgow-haskell-users@haskell.org
 Homepage: http://www.haskell.org/ghc/
-Synopsis: XXX
+Synopsis: The Glorious Glasgow Haskell Compiler.
 Description:
-        XXX
-Category: XXX
+    This package contains the @ghc@ executable, the user facing front-end
+    to the Glasgow Haskell Compiler.
+Category: Development
 Data-Dir: ..
 Data-Files: settings
 Build-Type: Simple
index 0b4f651..1f09b45 100644 (file)
@@ -10,7 +10,7 @@ synopsis:       GHC primitives
 cabal-version:  >=1.10
 build-type:     Custom
 description:
-    GHC primitives.
+    This package contains the primitive types and operations supplied by GHC.
 
 extra-source-files: changelog.md
 
index e9ceb46..85698c0 100644 (file)
@@ -8,9 +8,11 @@ license-file:   LICENSE
 category:       GHC
 maintainer:     ghc-devs@haskell.org
 bug-reports:    https://ghc.haskell.org/trac/ghc/newticket
-synopsis:       XXX
+synopsis:       The library supporting GHC's interactive interpreter
 description:
-        XXX
+            This library offers interfaces which mediate interactions between the
+            @ghci@ interactive shell and @iserv@, GHC's out-of-process interpreter
+            backend.
 cabal-version:  >=1.10
 build-type:     Simple
 extra-source-files: changelog.md
index 38c3f18..ade5fe4 100644 (file)
@@ -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
index f8f4263..04b3a58 100644 (file)
@@ -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
index 72afb72..50b5b69 100644 (file)
@@ -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
index 290af06..8730b4f 100644 (file)
@@ -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
index dba3b6d..8926db1 100644 (file)
@@ -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
 
index adc5230..d6dc8b5 100644 (file)
@@ -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
index 680c573..2c05da8 100644 (file)
@@ -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,
index 1697f7c..d6048a3 100644 (file)
@@ -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
index aca0783..5f76e1b 100644 (file)
@@ -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
index 7901aa2..d73c7fa 100644 (file)
@@ -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
index 5b185ee..93dc1cf 100644 (file)
@@ -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
 
index 47fb83d..efef5ec 100644 (file)
@@ -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