From 8b97635c41c998e6190f89c9883b2dcac5d8df09 Mon Sep 17 00:00:00 2001
From: defanor <defanor@uberspace.net>
Date: Fri, 22 Dec 2017 02:08:51 +0300
Subject: Refine documentation annotations and function names

---
 Pancake.hs               | 23 ++++++++++++-----------
 Pancake/Configuration.hs |  3 ++-
 Pancake/Rendering.hs     | 11 +++++++++--
 Pancake/Unclutter.hs     |  3 ++-
 4 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/Pancake.hs b/Pancake.hs
index 3a9f32a..1a74be8 100644
--- a/Pancake.hs
+++ b/Pancake.hs
@@ -187,17 +187,17 @@ goTo t u' = do
         let (prev, _) = history s
         in s {history = (take (historyDepth $ conf s) $ HE uri doc 0:prev, [])}
 
--- | Line number to block position.
-lineToPos :: [(Int, Int)] -> Int -> Int
-lineToPos bs n =
+-- | Line number to a fixed block's number.
+lineToBlockNumber :: [(Int, Int)] -> Int -> Int
+lineToBlockNumber bs n =
   case filter (\(_, (f, l)) -> f <= n && n < l) (zip [0..] bs) of
     [] -> 0
     xs -> (\(p, _) -> p) $
       maximumBy (\(_, (l, _)) (_, (l', _)) -> compare l l') xs
 
--- | Block position to line number.
-posToLine :: [(Int, Int)] -> Int -> Int
-posToLine bs p
+-- | Fixed block's number to line number.
+blockNumberToLine :: [(Int, Int)] -> Int -> Int
+blockNumberToLine bs p
   | length bs <= p = 1
   | otherwise = fst $ bs !! p
 
@@ -207,7 +207,8 @@ scrollToLine n = get >>= \st -> when (n > position st || embedded st) $ do
   -- update history entry's position
   case history st of
     (h : prev, next) -> modify $ \s ->
-      s {history = (h {hPos = lineToPos (rBlocks $ rendered st) n}:prev, next)}
+      s {history =
+         (h {hPos = lineToBlockNumber (rBlocks $ rendered st) n}:prev, next)}
     _ -> pure ()
   -- go to line
   if embedded st
@@ -217,10 +218,10 @@ scrollToLine n = get >>= \st -> when (n > position st || embedded st) $ do
       drop (position st) (rLines $ rendered st)
     modify (\s -> s { position = n })
 
--- | Scrolls to a block's position.
+-- | Scrolls to a fixed block's position.
 scrollToBlock :: MonadIO m => Int -> StateT LoopState m ()
 scrollToBlock b = get
-  >>= \s -> scrollToLine $ posToLine (rBlocks $ rendered s) b
+  >>= \s -> scrollToLine $ blockNumberToLine (rBlocks $ rendered s) b
 
 -- | Evaluates user commands.
 command :: MonadIO m => Command -> StateT LoopState m ()
@@ -358,7 +359,7 @@ command (SetPos mp) = let p = fromMaybe 0 mp in modify $ \s ->
     , history =
       case history s of
         (h:prev, next) ->
-          (h { hPos = lineToPos (rBlocks $ rendered s) p } : prev, next)
+          (h { hPos = lineToBlockNumber (rBlocks $ rendered s) p } : prev, next)
         other -> other}
 command Redisplay = do
   st <- get
@@ -369,7 +370,7 @@ command Redisplay = do
     _ -> putErrLn "There's nothing to redisplay"
 
 
--- | Reads commands, runs them.
+-- | Reads commands, runs them with 'command'.
 eventLoop :: MonadIO m => StateT LoopState m ()
 eventLoop = do
   st <- get
diff --git a/Pancake/Configuration.hs b/Pancake/Configuration.hs
index 772725e..bfac392 100644
--- a/Pancake/Configuration.hs
+++ b/Pancake/Configuration.hs
@@ -115,7 +115,8 @@ instance Default Config where
       curl = "curl --compressed -4 -L " ++
         "-w \"\n-pancake-\nuri: %{url_effective}\ntype: %{content_type}\n\" "
 
--- | Loads configuration from an XDG config directory.
+-- | Loads configuration from a given 'FilePath', or from an XDG
+-- config directory. Writes a default one if it doesn't exist.
 loadConfig :: MonadIO m => Maybe FilePath -> m Config
 loadConfig mp = liftIO $ do
   configPath <- case mp of
diff --git a/Pancake/Rendering.hs b/Pancake/Rendering.hs
index 5f7e31f..06181e3 100644
--- a/Pancake/Rendering.hs
+++ b/Pancake/Rendering.hs
@@ -96,11 +96,18 @@ data RS = RS { indentationLevel :: Int
 
 -- | This is what gets rendered.
 data RendererOutput = RLink URI
+                    -- ^ An URI reference.
                     | RNote [RendererOutput]
+                    -- ^ A note.
                     | RLine StyledLine
+                    -- ^ A line to render.
                     | RIdentifier String Int
+                    -- ^ An identifier.
                     | RBlock Int Int
-                    -- ^ number, start line, end line
+                    -- ^ A fixed block's position (start line and end
+                    -- line). These blocks reflect semantics and don't
+                    -- vary as the terminal width changes, so they are
+                    -- safe to rely on for position retention.
                     deriving (Show, Eq)
 
 -- | Show a reference.
@@ -125,7 +132,7 @@ rIdentifiers [] = []
 rIdentifiers (RIdentifier s i:xs) = (s, i) : rIdentifiers xs
 rIdentifiers (_:xs) = rIdentifiers xs
 
--- | Extracts block positions.
+-- | Extracts fixed block positions.
 rBlocks :: [RendererOutput] -> [(Int, Int)]
 rBlocks [] = []
 rBlocks (RBlock s e:xs) = (s, e) : rBlocks xs
diff --git a/Pancake/Unclutter.hs b/Pancake/Unclutter.hs
index 06ce098..cf5132e 100644
--- a/Pancake/Unclutter.hs
+++ b/Pancake/Unclutter.hs
@@ -51,7 +51,8 @@ import Control.Exception
 import Pancake.Common
 import Pancake.Configuration
 
--- | Tries to unclutter a document.
+-- | Tries to unclutter a document by applying an XSLT if it's
+-- available.
 tryUnclutter :: MonadIO m
              => [(Regex, String)]
              -- ^ Obtained with 'prepareUnclutter'.
-- 
cgit v1.2.3