diff --git a/hledger-lib/Hledger/Data/Types.hs b/hledger-lib/Hledger/Data/Types.hs
index 3c54fe2c0..82c7595b7 100644
--- a/hledger-lib/Hledger/Data/Types.hs
+++ b/hledger-lib/Hledger/Data/Types.hs
@@ -127,10 +127,10 @@ data Journal = Journal {
       jtxns :: [Transaction],
       open_timelog_entries :: [TimeLogEntry],
       historical_prices :: [HistoricalPrice],
-      final_comment_lines :: String,
-      filepath :: FilePath,
-      filereadtime :: ClockTime,
-      jtext :: String
+      final_comment_lines :: String, -- ^ any trailing comments from the journal file
+      filepath :: FilePath,      -- ^ file path of this journal
+      filereadtime :: ClockTime, -- ^ when this journal was read from its file
+      jtext :: String            -- ^ the raw text read from the journal's file
     } deriving (Eq, Typeable)
 
 data Ledger = Ledger {
diff --git a/hledger-lib/Hledger/Read/Common.hs b/hledger-lib/Hledger/Read/Common.hs
index 39546fdfe..435f72602 100644
--- a/hledger-lib/Hledger/Read/Common.hs
+++ b/hledger-lib/Hledger/Read/Common.hs
@@ -68,6 +68,8 @@ popParentAccount = do ctx0 <- getState
 getParentAccount :: GenParser tok JournalContext String
 getParentAccount = liftM (concat . reverse . ctxAccount) getState
 
+-- | Convert a possibly relative, possibly tilde-containing file path to an absolute one.
+-- using the current directory from a parsec source position. ~username is not supported.
 expandPath :: (MonadIO m) => SourcePos -> FilePath -> m FilePath
 expandPath pos fp = liftM mkAbsolute (expandHome fp)
   where
diff --git a/hledger-web/Hledger/Web/Settings.hs b/hledger-web/Hledger/Web/Settings.hs
index 4b0a4af09..f71b9c2d0 100644
--- a/hledger-web/Hledger/Web/Settings.hs
+++ b/hledger-web/Hledger/Web/Settings.hs
@@ -87,8 +87,9 @@ staticdir = datadir ++ "/static"
 templatesdir :: FilePath
 templatesdir = datadir ++ "/templates"
 
--- The following are compile-time macros. In production mode, the template
--- is read only once at startup, otherwise every time.
+-- The following are compile-time macros. If the file paths they point to
+-- don't exist, they will give an error (at compile time). In production
+-- mode, files are read once at compile time, otherwise repeatedly at runtime.
 
 hamletFile :: FilePath -> Q Exp
 #ifdef PRODUCTION