dev:web:docs

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

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 #-}

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 #-}

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)