lib: more Hledger.Read cleanup

hledger-lib/Hledger/Read.hs

@@ -4,18 +4,6 @@ This is the entry point to hledger's reading system, which can read
 Journals from various data formats. Use this module if you want to parse
 journal data or read journal files. Generally it should not be necessary
 to import modules below this one.
-
-Here's how most of these functions fit together:
-
-@
-readJournalFiles
- readJournalFile
-  requireJournalFileExists
-  readJournal
-   findReader
-   tryReaders
-@
-
 -}
 
 {-# LANGUAGE ScopedTypeVariables, OverloadedStrings #-}
@@ -127,11 +115,12 @@ readJournalFiles mformat mrulesfile assrt fs = do
 
 -- | @readJournalFile mformat mrulesfile assrt f@
 --
--- Read a Journal from this file (or stdin if the filename is -) or give
+-- Read a Journal from this file (or stdin if the file path is -).
--- an error message, using the specified data format or trying all known
+-- Assume the specified data format, or a format identified from the file path,
--- formats. A CSV conversion rules file may be specified for better
+-- or try all readers.
--- conversion of that format. Also there is a flag specifying whether
+-- A CSV conversion rules file may be specified for better conversion of CSV.
--- to check or ignore balance assertions in the journal.
+-- Also optionally check any balance assertions in the journal.
+-- If parsing or balance assertions fail, return an error message instead.
 readJournalFile :: Maybe StorageFormat -> Maybe FilePath -> Bool -> FilePath -> IO (Either String Journal)
 readJournalFile mformat mrulesfile assrt f = do
   requireJournalFileExists f