Add most common return values for `os` and `arch`

2 files changed, 47 insertions, 2 deletions

diff --git a/aclocal.m4 b/aclocal.m4
index 6db0600c6d..5a4ead657a 100644
--- a/aclocal.m4
+++ b/aclocal.m4
@@ -1919,7 +1919,9 @@ AC_MSG_CHECKING(for path to top of build tree)
 
 # GHC_CONVERT_CPU(cpu, target_var)
 # --------------------------------
-# converts cpu from gnu to ghc naming, and assigns the result to $target_var
+# Converts cpu from gnu to ghc naming, and assigns the result to $target_var.
+# Should you modify this list, you are invited to reflect the changes in 
+# `libraries/base/System/Info.hs`'s documentation.
 AC_DEFUN([GHC_CONVERT_CPU],[
 case "$1" in
   aarch64*)
diff --git a/libraries/base/System/Info.hs b/libraries/base/System/Info.hs
index c345cf9210..840a9b5a25 100644
--- a/libraries/base/System/Info.hs
+++ b/libraries/base/System/Info.hs
@@ -11,9 +11,11 @@
 -- Stability   :  experimental
 -- Portability :  portable
 --
--- Information about the characteristics of the host 
+-- Information about the characteristics of the host
 -- system lucky enough to run your program.
 --
+-- For a comprehensive listing of supported platforms, please refer to
+-- https://gitlab.haskell.org/ghc/ghc/-/wikis/platforms
 -----------------------------------------------------------------------------
 
 module System.Info
@@ -28,6 +30,10 @@ import Data.Version
 
 -- | The version of 'compilerName' with which the program was compiled
 -- or is being interpreted.
+-- 
+-- ==== __Example__
+-- > ghci> compilerVersion
+-- > Version {versionBranch = [8,8], versionTags = []}
 compilerVersion :: Version
 compilerVersion = Version [major, minor] []
   where (major, minor) = compilerVersionRaw `divMod` 100
@@ -35,15 +41,52 @@ compilerVersion = Version [major, minor] []
 #include "ghcplatform.h"
 
 -- | The operating system on which the program is running.
+-- Common values include:
+--
+--     * "darwin" — macOS
+--     * "freebsd"
+--     * "linux"
+--     * "linux-android"
+--     * "mingw32" — Windows
+--     * "netbsd"
+--     * "openbsd"
 os :: String
 os = HOST_OS
 
 -- | The machine architecture on which the program is running.
+-- Common values include:
+--
+--    * "aarch64"
+--    * "alpha"
+--    * "arm"
+--    * "hppa"
+--    * "hppa1_1"
+--    * "i386"
+--    * "ia64"
+--    * "m68k"
+--    * "mips"
+--    * "mipseb"
+--    * "mipsel"
+--    * "nios2"
+--    * "powerpc"
+--    * "powerpc64"
+--    * "powerpc64le"
+--    * "riscv32"
+--    * "riscv64"
+--    * "rs6000"
+--    * "s390"
+--    * "s390x"
+--    * "sh4"
+--    * "sparc"
+--    * "sparc64"
+--    * "vax"
+--    * "x86_64"
 arch :: String
 arch = HOST_ARCH
 
 -- | The Haskell implementation with which the program was compiled
 -- or is being interpreted.
+-- On the GHC platform, the value is "ghc".
 compilerName :: String
 compilerName = "ghc"