From 14a9ab5f289560f840585f1bc0d6a80c7f04a684 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Fri, 15 Dec 2023 13:06:43 -1000
Subject: [PATCH] dev:web:docs

---
 hledger-web/Hledger/Web/App.hs         | 23 ++++++++++++++++-------
 hledger-web/Hledger/Web/Application.hs |  5 +++++
 hledger-web/Hledger/Web/Main.hs        |  5 ++---
 hledger-web/Hledger/Web/Settings.hs    | 12 +++++++-----
 4 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/hledger-web/Hledger/Web/App.hs b/hledger-web/Hledger/Web/App.hs
index 6fbfc2d43..5c62b0a1d 100644
--- a/hledger-web/Hledger/Web/App.hs
+++ b/hledger-web/Hledger/Web/App.hs
@@ -1,3 +1,9 @@
+{-|
+Most of the definition of the web app is here.
+In the usual Yesod style, this defines the web app's core types and configuration,
+and then Application.hs completes the job.
+-}
+
 {-# OPTIONS_GHC -fno-warn-orphans  #-}
 {-# LANGUAGE CPP                   #-}
 {-# LANGUAGE FlexibleInstances     #-}
@@ -77,15 +83,18 @@ data App = App
 --   resources declared below. This is used in Handler.hs by the call to
 --   mkYesodDispatch
 --
--- What this function does *not* do is create a YesodSite instance for
--- App. Creating that instance requires all of the handler functions
+-- What this function does *not* do is create a YesodSite instance for App.
+-- AppCreating that instance requires all of the handler functions
 -- for our application to be in scope. However, the handler functions
 -- usually require access to the AppRoute datatype. Therefore, we
--- split these actions into two functions and place them in separate files.
+-- split these actions into two functions and place the other in a
+-- separate file (Application.hs).
+-- mkYesodData defines things like:
+--
+-- * type Handler = HandlerFor App   -- HandlerT App IO, https://www.yesodweb.com/book/routing-and-handlers#routing-and-handlers_handler_monad
+-- * type Widget = WidgetFor App ()  -- WidgetT App IO (), https://www.yesodweb.com/book/widgets
+--
 mkYesodData "App" $(parseRoutesFile "config/routes")
--- ^ defines things like:
--- type Handler = HandlerFor App   -- HandlerT App IO, https://www.yesodweb.com/book/routing-and-handlers#routing-and-handlers_handler_monad
--- type Widget = WidgetFor App ()  -- WidgetT App IO (), https://www.yesodweb.com/book/widgets
 
 type AppRoute = Route App
 type Form a = Html -> MForm Handler (FormResult a, Widget)
@@ -193,7 +202,7 @@ instance RenderMessage App FormMessage where
 data ViewData = VD
   { opts  :: WebOpts    -- ^ the command-line options at startup
   , today :: Day        -- ^ today's date (for queries containing relative dates)
-  , j     :: Journal    -- ^ the up-to-date parsed unfiltered journal
+  , j     :: Journal    -- ^ the up-to-date parsed unfiltered journal    -- XXX rename
   , qparam :: Text       -- ^ the current "q" request parameter
   , q     :: Query      -- ^ a query parsed from the q parameter
   , qopts :: [QueryOpt] -- ^ query options parsed from the q parameter
diff --git a/hledger-web/Hledger/Web/Application.hs b/hledger-web/Hledger/Web/Application.hs
index d34803c59..9a0d7fe32 100644
--- a/hledger-web/Hledger/Web/Application.hs
+++ b/hledger-web/Hledger/Web/Application.hs
@@ -1,3 +1,8 @@
+{-|
+Complete the definition of the web app begun in App.hs.
+This is always done in two files for (TH?) reasons.
+-}
+
 {-# OPTIONS_GHC -fno-warn-orphans #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE TemplateHaskell #-}
diff --git a/hledger-web/Hledger/Web/Main.hs b/hledger-web/Hledger/Web/Main.hs
index 3550c1e84..2dcdc69d0 100644
--- a/hledger-web/Hledger/Web/Main.hs
+++ b/hledger-web/Hledger/Web/Main.hs
@@ -1,9 +1,8 @@
 {-|
+hledger-web - a basic but robust web UI and JSON API server for hledger.
 
-hledger-web - a hledger add-on providing a web interface.
-Copyright (c) 2007-2020 Simon Michael <simon@joyful.com>
+Copyright (c) 2007-2023 Simon Michael <simon@joyful.com> and contributors.
 Released under GPL version 3 or later.
-
 -}
 
 {-# LANGUAGE MultiWayIf #-}
diff --git a/hledger-web/Hledger/Web/Settings.hs b/hledger-web/Hledger/Web/Settings.hs
index 9e5d7774b..be22e5c1e 100644
--- a/hledger-web/Hledger/Web/Settings.hs
+++ b/hledger-web/Hledger/Web/Settings.hs
@@ -1,11 +1,13 @@
+{-|
+Web app settings are centralized, as much as possible, into this file.
+This includes database connection settings, static file locations, etc.
+In addition, you can configure a number of different aspects of Yesod
+by overriding methods in the Yesod typeclass in App.hs.
+-}
+
 {-# LANGUAGE CPP               #-}
 {-# LANGUAGE OverloadedStrings #-}
 
--- | Settings are centralized, as much as possible, into this file. This
--- includes database connection settings, static file locations, etc.
--- In addition, you can configure a number of different aspects of Yesod
--- by overriding methods in the Yesod typeclass. That instance is
--- declared in the Foundation.hs file.
 module Hledger.Web.Settings where
 
 import Data.Default (def)