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/Configuration.hs |  3 ++-
 Pancake/Rendering.hs     | 11 +++++++++--
 Pancake/Unclutter.hs     |  3 ++-
 3 files changed, 13 insertions(+), 4 deletions(-)

(limited to 'Pancake')

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