From fffae7f57849c5a876b79b74be536d6a5a7a8a8f Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Thu, 21 Sep 2023 07:40:59 +0100
Subject: [PATCH] ;doc: main module haddock cleanups

---
 hledger-lib/Hledger.hs     | 23 ++++++++++++++++++++++-
 hledger-ui/Hledger/UI.hs   | 13 ++++++++++++-
 hledger-web/Hledger/Web.hs | 13 ++++++++++++-
 hledger/Hledger/Cli.hs     |  5 +----
 4 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/hledger-lib/Hledger.hs b/hledger-lib/Hledger.hs
index 49e77470d..2b10f03d2 100644
--- a/hledger-lib/Hledger.hs
+++ b/hledger-lib/Hledger.hs
@@ -1,4 +1,25 @@
-{-# LANGUAGE OverloadedStrings #-}
+{-|
+
+This is the root of the @hledger-lib@ package and the @Hledger.*@ module hierarchy.
+hledger-lib is the core engine used by various hledger UIs and tools,
+providing the main data types, file format parsers, reporting logic, and utilities.
+
+This is also the starting point for hledger's haddock docs,
+which describe Hledger's implementation for developers.
+These can be viewed
+in your code editor,
+or in a web browser (eg with @make haddock@),
+or on Hackage (starting at [hledger-lib:Hledger](https://hackage.haskell.org/package/hledger-lib/docs/Hledger.html)).
+
+== See also:
+
+- hledger:Hledger.Cli
+- hledger-ui:Hledger.UI
+- hledger-web:Hledger.Web
+- [The README files](https://github.com/search?q=repo%3Asimonmichael%2Fhledger+path%3A**%2FREADME*&type=code&ref=advsearch)
+- [The high-level developer docs](https://hledger.org/dev.html)
+
+-}
 
 module Hledger (
   module X
diff --git a/hledger-ui/Hledger/UI.hs b/hledger-ui/Hledger/UI.hs
index 8bcb778b0..d1c56c092 100644
--- a/hledger-ui/Hledger/UI.hs
+++ b/hledger-ui/Hledger/UI.hs
@@ -1,5 +1,16 @@
 {-|
-Re-export the modules of the hledger-ui program.
+
+This is the root module of the @hledger-ui@ package,
+providing hledger's terminal user interface.
+The main function, command-line options, and terminal themes are exported.
+
+== See also:
+
+- hledger-lib:Hledger
+- hledger:Hledger.Cli
+- [The README files](https://github.com/search?q=repo%3Asimonmichael%2Fhledger+path%3A**%2FREADME*&type=code&ref=advsearch)
+- [The high-level developer docs](https://hledger.org/dev.html)
+
 -}
 
 module Hledger.UI (
diff --git a/hledger-web/Hledger/Web.hs b/hledger-web/Hledger/Web.hs
index 89969ce87..be1eccc55 100644
--- a/hledger-web/Hledger/Web.hs
+++ b/hledger-web/Hledger/Web.hs
@@ -1,5 +1,16 @@
 {-|
-Re-export the modules of the hledger-web program.
+
+This is the root module of the @hledger-web@ package,
+providing hledger's web user interface and JSON API.
+The main function and command-line options are exported.
+
+== See also:
+
+- hledger-lib:Hledger
+- hledger:Hledger.Cli
+- [The README files](https://github.com/search?q=repo%3Asimonmichael%2Fhledger+path%3A**%2FREADME*&type=code&ref=advsearch)
+- [The high-level developer docs](https://hledger.org/dev.html)
+
 -}
 
 module Hledger.Web (
diff --git a/hledger/Hledger/Cli.hs b/hledger/Hledger/Cli.hs
index 20e0b134c..b77a938ae 100644
--- a/hledger/Hledger/Cli.hs
+++ b/hledger/Hledger/Cli.hs
@@ -17,10 +17,7 @@ and cmdargs:System.Concole.CmdArgs.Explicit
 
 See also:
 
-- [hledger-lib:Hledger]("Hledger")
-- [hledger:Hledger.Cli]("Hledger.Cli")
-- [hledger-ui:Hledger.UI]("Hledger.UI")
-- [hledger-web:Hledger.Web]("Hledger.Web")
+- hledger-lib:Hledger
 - [The README files](https://github.com/search?q=repo%3Asimonmichael%2Fhledger+path%3A**%2FREADME*&type=code&ref=advsearch)
 - [The high-level developer docs](https://hledger.org/dev.html)