Merge pull request #10941 from haskell/haddocks-for-autogen

Add Haddock documentation to Cabal's autogen modules

Author: mergify[bot]

Cabal/src/Distribution/Simple/Build/PackageInfoModule/Z.hs

@@ -24,6 +24,23 @@ render z_root = execWriter $ do
       return ()
   tell "{-# OPTIONS_GHC -Wno-missing-import-lists #-}\n"
   tell "{-# OPTIONS_GHC -w #-}\n"
+  tell "\n"
+  tell "{-|\n"
+  tell "Module      : PackageInfo_"
+  tell (zPackageName z_root)
+  tell "\n"
+  tell "Description : Contents of some of the package's Cabal file's fields.\n"
+  tell "\n"
+  tell "WARNING: This module was generated by Cabal. Any modifications will be\n"
+  tell "overwritten if the module is regenerated.\n"
+  tell "\n"
+  tell "This module exports values that record information from some of the fields of\n"
+  tell "the package's Cabal package description file (Cabal file).\n"
+  tell "\n"
+  tell "For further information about the fields in a Cabal file, see the Cabal User\n"
+  tell "Guide.\n"
+  tell "-}\n"
+  tell "\n"
   tell "module PackageInfo_"
   tell (zPackageName z_root)
   tell " (\n"
@@ -37,23 +54,29 @@ render z_root = execWriter $ do
   tell "import Data.Version (Version(..))\n"
   tell "import Prelude\n"
   tell "\n"
+  tell "-- |The content of the @name@ field of the package's Cabal file, but with any\n"
+  tell "-- hyphen characters replaced by underscore characters.\n"
   tell "name :: String\n"
   tell "name = "
   tell (show $ zPackageName z_root)
   tell "\n"
+  tell "-- |The content of the @version@ field of the package's Cabal file.\n"
   tell "version :: Version\n"
   tell "version = Version "
   tell (zVersionDigits z_root)
   tell " []\n"
   tell "\n"
+  tell "-- |The content of the @synopsis@ field of the package's Cabal file.\n"
   tell "synopsis :: String\n"
   tell "synopsis = "
   tell (show $ zSynopsis z_root)
   tell "\n"
+  tell "-- |The content of the @copyright@ field of the package's Cabal file.\n"
   tell "copyright :: String\n"
   tell "copyright = "
   tell (show $ zCopyright z_root)
   tell "\n"
+  tell "-- |The content of the @homepage@ field of the package's Cabal file.\n"
   tell "homepage :: String\n"
   tell "homepage = "
   tell (show $ zHomepage z_root)

Cabal/src/Distribution/Simple/Build/PathsModule/Z.hs

@@ -53,6 +53,25 @@ render z_root = execWriter $ do
     return ()
   tell "{-# OPTIONS_GHC -Wno-missing-import-lists #-}\n"
   tell "{-# OPTIONS_GHC -w #-}\n"
+  tell "\n"
+  tell "{-|\n"
+  tell "Module      : Paths_"
+  tell (zManglePkgName z_root (zPackageName z_root))
+  tell "\n"
+  tell "Description : Data file location, and package version and installation\n"
+  tell "              directories.\n"
+  tell "\n"
+  tell "WARNING: This module was generated by Cabal. Any modifications will be\n"
+  tell "overwritten if the module is regenerated.\n"
+  tell "\n"
+  tell "This module exports a function to locate data files, and values that record\n"
+  tell "the version of the package and some directories which the package has been\n"
+  tell "configured to be installed into.\n"
+  tell "\n"
+  tell "For further information about Cabal's options for its configuration step, and\n"
+  tell "their default values, see the Cabal User Guide.\n"
+  tell "-}\n"
+  tell "\n"
   tell "module Paths_"
   tell (zManglePkgName z_root (zPackageName z_root))
   tell " (\n"
@@ -101,17 +120,63 @@ render z_root = execWriter $ do
     tell "catchIO = Exception.catch\n"
     return ()
   tell "\n"
+  tell "-- |The package version.\n"
   tell "version :: Version\n"
   tell "version = Version "
   tell (zVersionDigits z_root)
   tell " []\n"
   tell "\n"
+  tell "-- |If the argument is a filename, the result is the name of a corresponding\n"
+  tell "-- file on the system on which the program is running, if the file were listed\n"
+  tell "-- in the @data-files@ field of the package's Cabal package description file.\n"
+  tell "-- No check is performed that the given filename is listed in that field.\n"
   tell "getDataFileName :: FilePath -> IO FilePath\n"
   tell "getDataFileName name = do\n"
   tell "  dir <- getDataDir\n"
   tell "  return (dir `joinFileName` name)\n"
   tell "\n"
-  tell "getBinDir, getLibDir, getDynLibDir, getDataDir, getLibexecDir, getSysconfDir :: IO FilePath\n"
+  tell "-- |The location of the directory specified by Cabal's @--bindir@ option (where\n"
+  tell "-- executables that the user might invoke are installed). This can be overridden\n"
+  tell "-- at runtime using the environment variable "
+  tell (zManglePkgName z_root (zPackageName z_root))
+  tell "_bindir.\n"
+  tell "getBinDir :: IO FilePath\n"
+  tell "\n"
+  tell "-- |The location of the directory specified by Cabal's @--libdir@ option (where\n"
+  tell "-- object libraries are installed). This can be overridden at runtime using the\n"
+  tell "-- environment variable "
+  tell (zManglePkgName z_root (zPackageName z_root))
+  tell "_libdir.\n"
+  tell "getLibDir :: IO FilePath\n"
+  tell "\n"
+  tell "-- |The location of the directory specified by Cabal's @--dynlibdir@ option\n"
+  tell "-- (where dynamic libraries are installed). This can be overridden at runtime\n"
+  tell "-- using the environment variable "
+  tell (zManglePkgName z_root (zPackageName z_root))
+  tell "_dynlibdir.\n"
+  tell "getDynLibDir :: IO FilePath\n"
+  tell "\n"
+  tell "-- |The location of the directory specified by Cabal's @--datadir@ option (where\n"
+  tell "-- architecture-independent data files are installed). This can be overridden at\n"
+  tell "-- runtime using the environment variable "
+  tell (zManglePkgName z_root (zPackageName z_root))
+  tell "_datadir.\n"
+  tell "getDataDir :: IO FilePath\n"
+  tell "\n"
+  tell "-- |The location of the directory specified by Cabal's @--libexedir@ option\n"
+  tell "-- (where executables that are not expected to be invoked directly by the user\n"
+  tell "-- are installed). This can be overridden at runtime using the environment\n"
+  tell "-- variable "
+  tell (zManglePkgName z_root (zPackageName z_root))
+  tell "_libexedir.\n"
+  tell "getLibexecDir :: IO FilePath\n"
+  tell "\n"
+  tell "-- |The location of the directory specified by Cabal's @--sysconfdir@ option\n"
+  tell "-- (where configuration files are installed). This can be overridden at runtime\n"
+  tell "-- using the environment variable "
+  tell (zManglePkgName z_root (zPackageName z_root))
+  tell "_sysconfdir.\n"
+  tell "getSysconfDir :: IO FilePath\n"
   tell "\n"
   let
     z_var0_function_defs = do

changelog.d/pr-10941

@@ -0,0 +1,8 @@
+---
+synopsis: "Haddock documentation added to Paths_pkgname and PackageInfo_pkgname modules"
+packages: [Cabal]
+prs: 10941
+---
+
+The automatically-generated modules `Paths_pkgname` and `PackageInfo_pkgname`
+now include Haddock documentation.

doc/cabal-package-description-file.rst

@@ -3083,9 +3083,10 @@ modules of the package. This module defines a function
 
     getDataFileName :: FilePath -> IO FilePath
 
-If the argument is a filename listed in the :pkg-field:`data-files` field, the
-result is the name of the corresponding file on the system on which the
-program is running.
+If the argument is a filename, the result is the name of a corresponding file on
+the system on which the program is running, if the filename were listed in the
+:pkg-field:`data-files` field. No check is performed that the given filename is
+listed in that field.
 
 .. Note::
 

templates/Paths_pkg.template.hs

@@ -14,6 +14,23 @@
 {% endif %}
 {-# OPTIONS_GHC -Wno-missing-import-lists #-}
 {-# OPTIONS_GHC -w #-}
+
+{-|
+Module      : Paths_{{ manglePkgName packageName }}
+Description : Data file location, and package version and installation
+              directories.
+
+WARNING: This module was generated by Cabal. Any modifications will be
+overwritten if the module is regenerated.
+
+This module exports a function to locate data files, and values that record
+the version of the package and some directories which the package has been
+configured to be installed into.
+
+For further information about Cabal's options for its configuration step, and
+their default values, see the Cabal User Guide.
+-}
+
 module Paths_{{ manglePkgName packageName }} (
     version,
     getBinDir, getLibDir, getDynLibDir, getDataDir, getLibexecDir,
@@ -52,15 +69,49 @@ catchIO :: IO a -> (Exception.IOException -> IO a) -> IO a
 catchIO = Exception.catch
 {% endif %}
 
+-- |The package version.
 version :: Version
 version = Version {{ versionDigits }} []
 
+-- |If the argument is a filename, the result is the name of a corresponding
+-- file on the system on which the program is running, if the file were listed
+-- in the @data-files@ field of the package's Cabal package description file.
+-- No check is performed that the given filename is listed in that field.
 getDataFileName :: FilePath -> IO FilePath
 getDataFileName name = do
   dir <- getDataDir
   return (dir `joinFileName` name)
 
-getBinDir, getLibDir, getDynLibDir, getDataDir, getLibexecDir, getSysconfDir :: IO FilePath
+-- |The location of the directory specified by Cabal's @--bindir@ option (where
+-- executables that the user might invoke are installed). This can be overridden
+-- at runtime using the environment variable {{ manglePkgName packageName }}_bindir.
+getBinDir :: IO FilePath
+
+-- |The location of the directory specified by Cabal's @--libdir@ option (where
+-- object libraries are installed). This can be overridden at runtime using the
+-- environment variable {{ manglePkgName packageName }}_libdir.
+getLibDir :: IO FilePath
+
+-- |The location of the directory specified by Cabal's @--dynlibdir@ option
+-- (where dynamic libraries are installed). This can be overridden at runtime
+-- using the environment variable {{ manglePkgName packageName }}_dynlibdir.
+getDynLibDir :: IO FilePath
+
+-- |The location of the directory specified by Cabal's @--datadir@ option (where
+-- architecture-independent data files are installed). This can be overridden at
+-- runtime using the environment variable {{ manglePkgName packageName }}_datadir.
+getDataDir :: IO FilePath
+
+-- |The location of the directory specified by Cabal's @--libexedir@ option
+-- (where executables that are not expected to be invoked directly by the user
+-- are installed). This can be overridden at runtime using the environment
+-- variable {{ manglePkgName packageName }}_libexedir.
+getLibexecDir :: IO FilePath
+
+-- |The location of the directory specified by Cabal's @--sysconfdir@ option
+-- (where configuration files are installed). This can be overridden at runtime
+-- using the environment variable {{ manglePkgName packageName }}_sysconfdir.
+getSysconfDir :: IO FilePath
 
 {% defblock function_defs %}
 minusFileName :: FilePath -> String -> FilePath